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Important Notice to Users 


No part of this publication may be reproduced, transmitted, or used in any form or by any means-- 
graphic, electronic, electrical, mechanical, optical, chemical, or otherwise including, but not limited 
to, photocopying, recording in any medium, taping, or use in any computer or information storage 

and retrieval system--without prior written permission from AT&T. 


This manual is intended for use by qualified computer and engineering professionals in accordance 
with generally accepted engineering practices and principles. AT&T reserves the right to revise this 
manual for any reason, including, but not limited to, conformity with standards promulgated by 
IEEE, ANSI, EIA, CCITT, ECMA or similar agencies; utilization of new advances in the State of 
technical arts; or to reflect changes in design of equipment or services described therein. While 
every effort has been made to ensure the accuracy of all information in this manual, AT&T 
expressly and absolutely disclaims any liability to any party of any kind in this PIClib User’s 
Guide, its updates, supplements, or special editions, whether such errors are omissions or Statements 
resulting from negligence, accident or any other cause. 


Warning 


The software described in this User’s Guide runs on equipment that generates, uses, and can radiate 
radio frequency energy, and if not installed and used in accordance with the instructions manual, 
may cause interference to radio communications. It has been tested and found to comply with the 
limits for a Class A computing device pursuant to Subpart J of Part 15 of FCC Rules, which are 
designed to provide reasonable protection against such interference when operated in a commercial 
environment. Operation of this equipment in a residential area is likely to cause interference in 
which case the users at their own expense will be required to take whatever measures may be 
required to correct the interference. 


Preface P-i 


LIMITED WARRANTY 


AT&T warrants this Pixel Machine is to be in good working order for a period of ninety (90) days 
from the date of purchase from AT&T or an authorized AT&T dealer. Should this product fail to be 
in good working order at any time during this 90-day warranty period, AT&T will, at its option, 
repair or replace this product at no additional charge except as set forth below. Repair parts and 
replacement Products will be furnished on an exchange basis and will either be new, remanufactured 
or refurbished, at the discretion of AT&T. All replaced parts and Products become the property of 
AT&T. This limited warranty does not include repair or damage to the Product resulting from 
accident, disaster, misuse, abuse, unauthorized modification of the Product, or other events outside 
AT&T’s reasonable control or not arising under normal operating conditions. 


Limited warranty service may be obtained by returning the Product during the 90-day warranty 
period to an authorized AT&T dealer, or by mail or carrier, to AT&T in accordance with the 
instructions provided to you by the Pixel Machines Hotline (1-800-544-0097 or (201) 563-2288) and 
providing proof of purchase date. If this Product is returned to AT&T, you agree to insure the Pro- 
duct or assume the risk of loss or damage in transit, to prepay shipping charges to the designated 
watranty service location and to ship the Product in the original shipping container or equivalent. 
Contact your authorized AT&T dealer or, if purchased directly from AT&T, your AT&T Account 
Executive for further information. 


All express or implied warranties for this product including the warranties of merchantability and 
fitness for a particular purpose are limited in duration to a period of 90 days from the date of pur- 
chase, and no warranties, whether express or implied, will apply after this period. Some states do 
not allow limitations on how long an implied warranty lasts, so the above limitations may not apply 
to you. 


If this product is not in good working order as warranted above, your sole remedy shall be repair or 
replacement as provided above, in no event will AT&T or its dealers or suppliers be liable to you 
for any damages, including any lost profits, lost savings or other incidental or consequential dam- 
ages arising out of the use of or inability to use such product, even if AT&T or an authorized dealer 
or supplier has been advised of the possibility of such damages, or for any claim by any other party. 


Some states do not allow the exclusion or limitation of incidental or consequential damages so the 
above limitation or exclusion may not apply to you. 


This warranty gives you specific legal rights, and you may also have other rights which may vary 
from state to state. 
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About Trademarks 


Sun Workstation® is a registered trademark of Sun Microsystems, Inc. 
UNIX® System, Operating System, is a registered trademark of AT&T. 
WE® DSP32 Digital Signal Processor is a registered trademark of AT&T. 
PIClib™ is a registered trademark of AT&T Pixel Machines. 

RAYlib™ is a registered trademark of AT&T Pixel Machines. 

RTSlib™ is a registered trademark of AT&T Pixel Machines. 

IMGlib™ is a registered trademark of AT&T Pixel Machines. 

DEVtools™ is a registered trademark of AT&T Pixel Machines. 


Copyright© June 1990 by AT&T 
All rights reserved 
Printed in USA 


No part of his publication may be reproduced, transmitted, or used by any means-~ graphic, elec- 
tronic, electrical, mechanical, optical, chemical, or otherwise including but not limited to photocopy- 
ing, recording in any medium, taping, or use in any computer or information storage and retrieval 
system--without prior written permission from AT&T. 
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Preface 


This document presents a description of the PXM 900 Series system commands and PIClib func- 
tions and is intended for users who are familiar with C language and experienced in developing pro- 
grams. The information presented here is not introductory and assumes that the reader has 
knowledge of basic programming concepts and the UNIX® Operating System. 
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Pixel Machine Features 


Pixel Machines are graphics generation and display systems that provide high quality image com- 
puting. The systems are programmable and modular, and are designed to execute complex graphics 
functions at very high speeds. 


The Pixel Machines offer a complete set of system commands and a powerful graphics library, 
PIClib, for generating a multitude of images. PIClib’s functions reside in the host computer and 
provide an interface between your application program and the Pixel Machine. Some of the 
highlights of PIClib include: 


high-level, 3D object generation (including patches, quadrics, and superquadrics) 
flat, Gouraud and Phong shading 

texture mapping onto 2D or 3D surfaces 

multiple light sources of different types 

antialiasing by supersampling for photorealistic 3D rendering 

32-bit floating point z-buffer for highly accurate depth precision 

32-bit double buffering 

a robust set of interactive 3D graphics functions 


a unique set of rgbz buffer copy routines 


The application programs are written in C. For more information on the C programming language, 
refer to The C Programming Language by Brian W. Kernighan and Dennis M. Ritchie (1978, 
Prentice-Hall, Inc., Englewood Cliffs, New Jersey, or the updated 1988 edition). 
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Documentation Conventions 


The information in this guide is presented in the following way: 
mw Square brackets [] indicate options; parenthesis () indicate arguments. 
m Variables and user—supplied names are printed in italics. 
m Constants and return values are printed in helvetica. 


m Each command and function is addressed separately. The discussion includes a description of 
the command or function’s purpose and operation. This is followed by its syntax and com- 
mand usage format and, finally, by an explanation of the arguments; for example: 


PICcircle(x,y,r) 
float x,y; 


xy = the coordinates of the circle’s centerpoint 


r = _ the circle’s radius 


m= Where appropriate, examples and illustrations are included to further clarify the use of a com- 
mand or function. 
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Software Structure Overview 


To set-up your software environment on the Pixel Machine for PIClib, you need two tapes: 
PXMtools and PIClib. PXMtools contains the system commands and data files that are not unique 
to any one Pixel Machine software library. These commands include what you need to initialize the 
machine and to set-up your environment variables, along with files containing cursor and font data. 


These tapes must be loaded according to the instructions in their accompanying Release Notes. 


The following two sections describe the directory structures and contents of PXMtools and PIClib. 


PXMtools Directory Structure 


PXMtools has the following directory structure: 


pxmtools: 
bin — PXMtools commands 
boot — Pixel Machine DSP executables 
cpic - gamma correction data for calibrating various monitors 


cursors — bitmaps that define cursors 
fonts  - vector fonts used with various demos 
icons — icons for some of the demos 
include — user include files 
locks — Pixel Machine lockfile directory-permissions must be 777. 
man  -— manual pages: 
manl — source for command man pages 
man4 — source for image header man pages 
catl — command man pages 
cat4 — image header man pages 


PIClib Directory Structure 
PIClib has the following directory structure: 


piclib: 
bin — Shell level PiClib utilities 
picclear, picdisp, picsave, piccompress, pictexture, picbroadv 
boot — Pixel Machine DSP executables 
demo — demonstration programs 
bin — executable demo programs with scripts 
data — object and image data files 
obj — object files 
src — source files 
include — user include files 
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lib — library directory contains the following libraries: 
piclib.a — host library 
piclib_p.a — profiled host library 
piclib_ffpa.a — host library, floating point (Sun 3 only) 
piclib_ffpa_p.a — profiled host library, floating point (Sun 3 only) 

— in the FORTRAN version, this directory contains: 

piclib_ffpa_pf.a — profiled host library, floating point, FORTRAN version (Sun 3 only) 
piclib_ffpaf.a — host library, floating point, FORTRAN version (Sun 3 only) 
piclib_pf.a — profiled host library, FORTRAN version 
piclibf.a — host library, FORTRAN version 

man — manual pages: 
whatis — list of PIClib functions 
mani — source for command man pages 
man3 — source for function man pages 
man4 — source for image header man pages 
catl -~ command man pages 
cat3. — function man pages 
cat4 — image header man pages 
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Getting Started 


Before you can compile and run your programs, you need to make sure that the hardware is initial- 
ized and the software environment is set up correctly. When you first turn on the Pixel Machine, 
you must initialize the hardware to a known state. This is accomplished by executing the hypinit 
command. For more information about hypinit, see the manual page that came with the PXMtools 
commands and the section on hypinit in Chapter 2 of this User’s Guide. 


The software environment must be set up at installation time, after power-up, and after any changes 
to the system’s configurations (for example, upgrading the Pixel Machine or changing the Transfor- 
mation Pipeline configuration). The procedures for setting up the software environment are 
described below. 


Defining the Software Environment 


Before using the Pixel Machine, the proper environment must be created. You must set the Pixel 
Machine environment variables for each login on the host computer. These variables are set in one 
of the following three ways: 


1. As commands typed manually from the UNIX® system prompt. 


2. As statements in your .login and .cshre files (C shell [csh]) or as statements in your .profile 
and .env files (Korn shell [ksh]). 


3. As statements in a system file, such as /etc/profile. 


Environment Variables 


The /usr/hyper directory contains sample files for defining the Pixel Machine environment. These 
files are named: 


-hyper_login 
-hyper_cshre 
-hyper_profile 
-hyper_env 


If you are using csh, you can source .hyper_login and .hyper_cshrc into your .login file. Edit 
your .login file, and add the following to the end of the file: 


source /usr/hyper/.hyper_login 
source /usr/hyper/.hyper_cshre 
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If you are using ksh, you can . (dot) -hyper_profile and -hyper_env into your .profile. Edit 
your .profile and add the following to the end of the file: 


/usr/hyper/.hyper profile 
/usr/hyper/ .hyper_env 


When setting up your environment, refer to the variable descriptions below. These variables should 
be included in your .profile, .login or system file. 


The HYPER_MODEL variable specifies the Pixel Machine model and Transformation Pipeline 
configuration. The table below describes the values that can be assigned to this variable. 


EES ae 
16 Pixel Machine 916 | single Pipe| 1024x1024 


eres 
Pixel Machine 916|dual Pipe |1024x1024 


916 
ae ey Eee) 
Pixel Machine 920] single Pipe| 1280x1024 
ae 


920d Pixel Machine 920jdual Pipe |1280x1024 


Pixel Machine 932 | single Pipe| 1024x1024 


[of ae re ee | 
ee ee ee ee 

932d Pixel Machine 932|dual Pipe | 1024x1024 
[SRS re ee | 
: 
[ee 










































ee ee Ue ee 
Pixel Machine 940 | single Pipe] 1280x1024 


940d Pixel Machine 940|dual Pipe | 1280x1024 


96 Pixel Machine 964 1024x1024 
964d 

964X 

964dx 












Pixel Machine 964 | dual Pipe | 1024x1024 
SO Te, NE RT 
Pixel Machine 964 | single Pipe| 1280x1024 







[964dxK Pixel Machine 964 | dual Pipe 


A lower case ''n” appended to the model number indicates an NTSC model whose reso- 
lution is 720x486, 


1280x1024 





A lower case “p” appended to the model number indicates a PAL model whose resolu- 
tion is XXX. 





A lower case “'z” appended to the model number indicates zero pipes. 


An “X” appended to the model number indicates a high resolution monitor. 
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The HYPER_PATH variable specifies the full pathname to the host directory that contains the 
Pixel Machine software (for example, /usr/hyper) 


The HYPER _PIPE variable specifies the pipeline configuration (serial or parallel) for systems with 
two transformation pipelines. 


The HYPER_UNIT variable specifies the Pixel Machine unit number. Up to four machines (num- 
bered 0, 1, 2, 3) can be connected to a host computer. The HYPER_GAMMA variable controls 
how the color tables are updated by hypinit. If HYPER_GAMMA is set and is not null, it is 
used as the the name of a file that contains a gamma correction table. If HYPER_GAMMA is 
not set or is null, a linear ramp is loaded into the color tables. If HYPER_GAMMA does not 
contain an absolute pathname, it is used as a filename in the $HYPER_PATH/cpic directory. Rela- 
tive pathnames are not supported. 


The video control parameters are set based on the HYPER_MODEL and HYPER_VIDEO 
environment variables. The HYPER_VIDEO variable contains a string that is parsed to produce a 
value that is passed to DEVset_video_options(). The string in HYPER_VIDEO must be of the 
format: 





The value after the equal sign must be one of the values listed in braces. The first value is the 
default; spaces in the string are ignored. 


Examples: 





In addition to defining the Pixel Machine-specific environment variables, you can also update your 
PATH variable(s) to provide easy access to Pixel Machine software, demos and manual pages. 


To update your PATH variable, add the following directories: 
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$HYPER_PATH/bin Allows you to run the PXMtools system commands 
(e.g., hypinit (see Chapter 2 for more information)) 
and the PIClib utilities (e.g., picclear (see Chapter 2 for more information)) 
from your current working directory. 


$HYPER_PATH/piclib/demo/bin Allows you to run PIClib demos from your current 
working directory. 


To update your MANPATH variable, add the following directories: 


$HYPER_PATH/man 


$HYPER_PATH/piclib/man Allows you to access PXMtools manual pages as well as PICIib manual 
pages from your current 
working directory. 


To see a list of what your environment variables are set to, type the hypenv command. For more 
information about hypenv, refer to Chapter 2 of this User’s Guide and the hypenv(1) manual page 
that came with the PXMtools. 


If you upgrade or change your present Pixel Machine, you need to redefine the environ- 
ment variables. 





Setting Environment Variables Using csh 


The following example illustrates the csh commands you need to specify to define the Pixel 
Machine environment for a Model 964d with the transformation pipelines configured in serial mode. 


Be sure to enter each environment variable on a separate line. 





The following can be added to your .login file: 
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setenv HYPER MODEL 964d 
setenv HYPER PATH /usr/hyper 


setenv HYPER_PIPE serial 
setenv HYPER UNIT 0 
setenv MANPATH ${MANPATH}:$HYPER_PATH/man:$HYPER_PATH/piclib/man 


setenv HYPER_GAMMA 
setenv HYPER_VIDEO 


set path = ( ${path} $HYPER_PATH/bin $HYPER_PATH/demo/piclib/bin \ 
$HYPER_PATH/demo/raylib/bin) 


Alias definitions provide a ‘‘short—cut’’ for defining variables. The following lines can be added to 
your .cshre file. 


alias hypmodel *setenv HYPER MODEL = \!*’ 


alias hypipe *setenv HYPER_PIPE \Ve? 
alias hypunit setenv HYPER_UNIT Ve 
alias hypath *setenv HYPER PATH \Ve? 


alias hypgamma setenv HYPER GAMMA _ \!*’ 
alias hypvideo *setenv HYPER_VIDEO \We 


Once the above aliases have been established, you can use them to define environment variables. 
For example, if you need to redefine the HYPER_PIPE variable to designate a parallel pipeline 
configuration, you can type hypipe parallel instead of setenv HYPER PIPE parallel . 


Setting Environment Variables Using ksh 


The following example illustrates the ksh commands you need to specify to define the Pixel 
Machine environment for a Model 964d with the transformation pipelines configured in serial mode. 
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HYPER_MODEL=964d 

HYPER_PATH=/usr/hyper 

HYPER _PIPE=serial 

HYPER _UNIT=0 

HYPER_GAMMA 

HYPER VIDEO 

PATH=$PATH:$HYPER_PATH/bin:$HYPER_PATH/piclib/demo/bin: 
MANPATH=$MANPATH:$HYPER_PATH/man:$HYPER_PATH/piclib/man 

export HYPER_MODEL HYPER_PATH HYPER PIPE HYPER_UNIT HYPER_GAMMA HYPER_VIDEO 
export MANPATH PATH 


Alias definitions provide a ‘‘short-cut’’ for defining variables. The following lines can be added to 
your .env file. 


hypmodel() { HYPER_MODEL=$1; } 
hypipeQ) { HYPER_PIPE=$1; } 
hypunit() { HYPER_UNIT=$1; } 
hypath) { HYPER PATH=$1; } 
hypgamma() { HYPER_GAMMA=$1; } 
hypvideo() { HYPER_VIDEO=$1; } 
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Compiling and Running Programs 


At the beginning of each C application program, you must include a header file for PIClib. This file 
includes type definitions, constants, and external definitions, and is included by the following state- 
ment: 


#include <piclib.h> 


The first graphics function called within an application program is usually PICinit(). This function 
initializes and resets the PIClib library, and opens the Pixel Machine device, stapic all the nodes in 
the system, and resets all graphical parameters to their default values as described in PICreset() 
manual page. PICinit() returns a value of PIC_ERR_OK if the initialization is successful, or a 
PIC_ERR_OPEN if it failed. For a complete description of the functionality, see the PICinit(3) 
manual page in the PIClib Reference Manual. 


The last graphics function called within an application program is usually PICexit(). Be sure to 
include it at the end of your program. 


To compile your graphics program, link piclib.a and the math library as follows: 





where, [file.c] is the name of the file containing the program. You can also link with versions of 
PIClib that include profiling and different floating point options. 


The system will compile your program and create an executable file called a.out. To run the pro- 
gram, rename the file to whatever file you have chosen and type the name of this executable file. 


Using Macros 


The file PICMAC.h contains macros that you can use to speed up the processing of your programs 
(see Appendix A for a list of the macros. These macros avoid the overhead of calling and returning 
from functions and of converting floating point arguments into double precision and back into single 
precision. The file is located in /usr/hyper/include. Be sure to include it at the top of your pro- 
gram if you want to use the macros for faster command execution. The macro for a PIClib com- 
mand is identical to the PIClib command,.except the PIC prefix is replaced with PICMAC (e.g., 
PIC_point 3d becomes PICMAC point_3d). 
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Pixel Machine System Commands and Utilities 


System Commands 
hypdis 

hypenv 

hypfree 

hypid 

hypinit 

hyplock 

hypstat 

hypunlock 

hypversion 


PIClib Utility Programs 
picalpha 
picbars 
picboot 
picbroadv 
picbroadz 
picbtof 
picdisp 
picetof 
picftob 
picftoe 
picgamma 
picinit 
piclear 
piclens 
picsave 
pictexture 
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Pixel Machine System Commands and Utilities 


The system commands (UNIX system commands typed on the command line) and utilities (PICIib 
programs) allow you to perform utility and administrative functions, such as initializing the 
hardware, loading the PIClib processor programs into the transformation pipeline(s) and pixel nodes, 
or simply locking your Pixel Machine. 


The system commands described in this section are: 


Prints the software version. 


For more information on the use of these commands, see the manual pages that came with your 
PXMtools software. 




















The system utilities described in this section are: 
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Saves an image to disk 
Displays current texture loaded into VRAM 
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System Commands 


hypdis 


hypdis writes a zero to the mode register of each pixel board in a system, thereby effectively 
removing the board from consideration during writes to the broadcast FIFO and during processor 
synchronization operations. 


hypdis is typically used to reconfigure a Pixel Machine to a lower model number for testing pur- 
poses or when a pixel board becomes inoperative. 


The following example shows how to configure a Pixel Machine with 64 nodes as a 940: 
HYPER MODEL=940d 
hypdis 

The hypdis command should always be followed by a hypinit. 


It is important to note that Pixel Machines equipped with the serial I/O feature will not 
work when a system is configured as a smaller model using hypdis. 





Also note that pipe boards are unaffected by hypdis, therefore hypdis cannot be used to configure 
a 964d as a 964, for example. 
hypenv 


The hypenv command displays the current values of the Pixel Machine environment variables. 
The environment variables must be set on the host workstation either in a login procedure or before 
using the Pixel Machine. (See Chapter 1 of this Guide for procedures for setting Pixel Machine 
environment variables.) If no options are specified, the status of all environment variables are 
displayed. 


Command usage is: 


hypenv [-D][-MI[-PII-UI[- GI[-VII-All-ul 


The options are as follows: 
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-D Print current value of HYPER_PIPE (serial or parallel) 

~M Print current value of HYPER MODEL environment variable 
-P Print current value of HYPER_PATH environment variable 

-U ‘Print current value of HYPER _UNIT environment variable 

-G Print current value of HYPER_-GAMMA environment variable 
~V Print current value of HYPER_VIDEO environment variable 
-A Print current value of HYPER_ADDRESS environment variable 


—u Print command usage format 


If you enter hypenv, the system displays the following typical response: 


Model: 964d Pipe: parallel Unit: 0 Path: /usr/hyper 


The HYPER_ADDRESS environment variable should ONLY be used with the SGI 
Power Series host. Please read the SGI Release Notes for more information on this 
variable. HYPER_ADDRESS should NOT be used or set with any other Pixel 
Machines hosts. 





hypfree 


The hypfree command releases one or more Pixel Machines that were locked with the hyplock 
command. If no options are specified, the command releases only the current unit. 


Command usage is: 
hypfree [—a][-u] 


The options are as follows: 


-a Free all units 


—u___ Print command usage format 
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NN 


hypid 
The hypid command generates a list of ID data on the nodes in the Pixel Machine. 
Command usage is: 


hypid [—all-d node}{-g node][-ul] 


The options are as follows: 


-a Print ID data on all nodes 

—d node Print ID data of pixel node number node or all 

—g node Print ID data of transformation node number node or all 
-u Print command usage format 


If you enter hypid —d1, the system displays the following typical response for a Pixel Machine 
964 model: 





The ID data provides the following information: 


m node id contains the sequential numbering of the transformation and pixel nodes. The pixel 
nodes range from 0 to n (n = 63 on a model 964). The transformation nodes range from 0 to 
8 for a single pipe configuration; from 0 to 17 for a dual pipe configuration. 


x nodes and y nodes indicate the configuration of the buffer in an N x M array. 
x offset and y offset indicate the position of the processor in the 2D array. 


program lists the name of the DSP executable program that is loaded into memory. 


semaphore contains system information 
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hypinit 


Each time you power up the system, you need to initialize it to a known state. The hypinit com- 
mand initializes the Pixel Machine to its default state. If no options are specified, hypinit initial- 
izes the transformation nodes and FIFOs, the pixel nodes, the drawing mode register, the transfor- 
mation pipeline, and the video. 


You can also use this command to reinitialize the Pixel Machine whenever you want the system to 
return to its initial state. 


Command usage is: 
hypinit [—b] [—d] [-g] [-m] [-n] [-p] [-q] [-Q] [-r] [-v] -V] [-u] 


The following options may be used to limit initialization: 


-b Initialize the VME bus repeater 
-d Initialize the pixel nodes 
-g Initialize the pipe nodes 


-m_ Initialize the pixel mode register to the current configuration 
model, disable overlay video, and turn off testing mode 


—n Do not initialize the video 


-p Reconfigure pipelines in series or parallel based on the 
environment variable 


-q _ Enables pipelined writes 

~Q __ Disables pipelined writes 

-r Reset input and output pipeline FIFOs 

-v enable verbose mode 

-V_ Initialize video registers and lookup tables 


-u_— Print command usage format 


If you enter hypinit —v, the system displays the following typical response: 
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hyplock 


The hyplock command locks the current Pixel Machine and prevents other users who are timeshar- 
ing the system from accessing it. (The Pixel Machine is not multitasking.) Before you log off, 
remember to unlock the system by executing the hypfree command. 


Command usage: 


hyplock [-u] 


The options are as follows: 


-u__- Print command usage format 
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hypstat 
The hypstat command displays the system status of the Pixel Machine. 


Command usage is: 
hypstat [—u] 
The options are as follows: 


-u Print command usage format 


If you execute hypstat, the system displays the the same message as hypinit —v, which is 
described above. If you get an error message, enter the hypinit command first and then hypstat. 


hypunlock 


The hypunlock shell script can be used to unconditionally unlock a particular Pixel Machine. If 
unit is specified, that Pixel Machine is unlocked, otherwise the machine specified by 
$HYPER_UNIT is unlocked. The hypunlock command is typically used when someone has pre- 
viously locked the Pixel Machine (using hyplock) and forgotten to free the Pixel Machine after 
using it. 


Command usage is: 
hypunlock [unit] 
This command should only be used as a last resort when you are sure that no one else is currently 
using the Pixel Machine. 
hypversion 


hypversion with no options displays the software product, version, and date of the installed 
software. Specific products can have version information displayed by using the appropriate option. 


Command usage is: 


hypversion [-p] [-d] [-r] [-s] [-u] 
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The options are as follows: 


-p Print version of PIClib 

-d___ Print version of DEVtools 

-r Print version of RAYIib 

-—s Print version of RTSlib (Simulation Library) 


-u__— Print command usage format 
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Following are brief descriptions of the PIClib system commands. For more detailed information, 
see the manual pages in section 1 of the PlClibReference Manual. 

picalpha 

picalpha turns the display of the alpha channel on or off. With an argument, it turns on the 
display; without an argument, the display is turned off. 

picbars 


picbars displays color bars on the screen. Followed by an argument, it displays logarithmic color 
bars, and with no argument, it displays linear color bars. 


ore This tool is useful for calibrating equipment such as cameras and monitors. 


picboot ; 

picboot downloads PIClib into the Pixel Machine. This command checks each pipe and pixel node 
to see if the correct PIClib module is loaded. If it isn’t, picboot loads it. 

picbroadv 


picbroadv broadcasts pixels to extended VRAM in many formats. The following image formats 
are supported: 


PIC_RGB_PACKED PIXELS 
PIC_RGBA_PACKED PIXELS 
PIC_ABGR_PACKED PIXELS 


This command is useful for loading texture maps. 


Command usage is: 
picbroadv [—p x y][~s npixels nlines] [—o0 xoffset yoffset] [-d] [—v] filename 


The options are as follows: 
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—pxy Specifies the starting pixel location in the plane of memory in x and y pixel 
coordinates. The default is 0 0. 


—s npixels nlines Specifies the number of pixels and number of scan lines to 
download. The default is the size of the image as 
specified in the image header. 


—o xoffset yoffset Specifies the number of pixels (in the x and y direction) to offset 
the 
image by before downloading. This number of pixels and lines will be 
skipped in the image file. The default is 0 0. 


-d . Uses the default starting pixel location that is specified in the 
image file. This overrides the —-p option. 
-v Print verbose output 
picbroadz 


picbroadz braodcasts pixels to extended DRAM in many different formats. The following image 
formats are supported: 


PIC_RGB_PACKED PIXELS 
PIC_RGBA_PACKED_ PIXELS 
PIC_ABGR_PACKED PIXELS 


Command usage is: 


picbroadz[-p x y][-s npixels nlines] [-o xoffset yoffset] [-d] [-v] filename 


The options are as follows: 
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—pxy Specifies the starting pixel location in the plane of memory in x and y pixel 
coordinates. The default is 0 0. 


~s npixels nlines Specifies the number of pixels and number of scan lines to 
download. The default is the size of the image as 
specified in the image header. 


—o xoffset yoffset Specifies the number of pixels (in the x and y direction) to offset 
the 
image by before downloading. This number of pixels and lines will be 
skipped in the image file. The default is 0 0. 


-d Uses the default starting pixel location that is specified in the 
image file. This overrides the —p option. 


-v Print verbose output 


picbtof 


picbtof copies the contents of the back buffer to the front buffer; the result is immediately seen on 
the display. 


This command does not take any options. 





picdisp 
picdisp downloads and/or displays an image in many different formats. 
The image formats supported are: 


PIC_RGB PIXELS 

PIC_RGB PACKED PIXELS 
PIC_RGBA_PACKED PIXELS 
PIC_ABGR_ PACKED PIXELS 
PIC_RGB_ENCODED PIXELS 


Command usage is: 


picdisp [—p initx inity] [-s npixl nline] [-o xoffset yoffset] —b [front! back‘ extended] 
—[vdc] filename [—C composite_mode] filename 
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The options are as follows: 


—p initx inity 
~s npixl nline 


—o xoffset yoffset 


—b buffer 


—V 


Examples: 


PIClib Utility Programs 


Specifies the starting pixel location on the screen in x and y pixel coordinates. 
The default is 0 0. 


Specifies the number of pixels and number of scan lines to download. The 
default is the size of the image as specified in the image header. 


Specifies the number of pixels (in the x and y directions) to offset the 
image by before downloading. This number of pixels and lines will be skipped in the 
image file. The default is 0 0. 


Specifies to which segment of memory pixels should be downloaded (front is the default). 
If front is specified, pixels are downloaded to the visible buffer of VRAM. 

If back is specified, pixels are downloaded to the invisible buffer of VRAM. 

If extended is specified, pixels are downloaded to the invisible buffer 

of extended VRAM. 


picdisp uses the default starting pixel location as specified in the image file. 
This option overrides the —p option. 


Copies the image to the front buffer. After the copy, the front and back buffers 
are identical. 


Specifies composite mode. The following modes, in either upper or lower case, are supported. 
NO_ COMPOSITE 


Prints verbose output 


picdisp —c —b back filename 


displays the image in both front and back buffers. 


picdisp test.img 
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In this example the image is displayed on the screen from (0,0). 
picdisp —d test.img 


The image is displayed on the screen in the way it was stored. That is, if the image was displayed 
in screen coordinate space from (500,500) to (800,800) when it was saved, the image will be 
displayed in the same coordinate space. 


picdisp —p 0 0 -s 255 255 -o0 0 0 —b front —Vv fest.img 


test.img is displayed on the screen at the starting point (0,0) with a size of 255,255. The offset into 
the image is (0,0), and the image is displayed in the front buffer. 


For this release ONLY, picdisp can also display images stored in the old image format. 
NOTE 


picdisp filename [initx inity [finalx finaly lifromx ifromy [itox itoy]]]] 


picetof 


picetof copies the contents of the extended VRAM buffer to the front buffer; the result is immedi- 
ately seen on the display. 


picetof does not take any arguments. 
NOTE 


picftob 


picftob copies the contents of the front buffer to the back buffer. The display on the screen 
remains unchanged. 


picftob does not take any arguments. 
NOTE 
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picftoe 
picftoe copies the contents of the front buffer to the extended VRAM buffer. 


“| picftoe does not take any arguments. 
NOTE 


picgamma 

picgamma creates gamma corrected lookup tables and loads these tables into the Pixel Machine. 
Without any arguments, the gamma values used for r, g, b are 1.0. If one argument is specified, r, 
g, b are set to that argument. If three arguments are specified, the gamma values for r, g, b are set 
to the arguments, respectively. 

picinit 

picinit resets the Pixel Machine to its default values. This command is useful for returning the 
machine to a normal state. 


picinit does not take any arguments. 





piclear 


piclear clears the front and back buffers with the specified rgb on the command line. If rgb is not 
specified, it clears the screen to black. The alpha plane is set to zero, and the z-buffer is cleared to 
its default. 


Command usage is: 


piclear [~b] [r g b] 
float r,g,b; 


The options are as follows: 
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-b Clears the back buffer only 


rgb _ Specifies the color to be used in clearing the buffers. 
r, g and b range from 0.0 to 1.0. 


piclens 


piclens is an interactive tool that allows the user to roam around the display and magnify segments 
of it. The image on the screen can be magnified up to 128 times. The image cannot be scaled 
down below its original size (i.e., 1). The size of the window is 256 X 256 pixels. 


When piclens is invoked, a mouse playground window appears on the host machine. The three 
buttons on the mouse do the following: 


Right button: the magnification factor is doubled 

Left button: the magnification factor is halved 

Middle button: sets the point to be magnified 

Keyboard keys: the keyboard keys can be upper or lower case, and they do the following: 


6 G-— toggle grid on/off in magnification window. The current pixel is 
highlighted with a red boundary. 


O arrow keys — move position by one pixel in the appropriate direction. 
Pre-fixing the arrow keys with a number, moves the position by given 
amount. 


Oo Q- quit 


piclens does not take any arguments. 





picsave 
picsave saves an image to disk in many different formats. 
Command usage is: 


picsave [-p initx inity] [-s npixels nlines] [-m rgb|rgba|agbr] [—b front| back] 
[-v] filename 
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The options are as follows: 


“pry 
-s npixels nlines 


—m mode 


—b buffer 


Iv: 


pictexture 


PIClib Utility Programs 


Specifies the starting pixel location on the screen in pixel coordinates. 
The default is 0,0. 


Specifies the number of pixels and number of scan lines to be saved. The default is 
the entire screen. 


Specifies how pixels are stored. mode is one of the following (rgba is the 
default): 


tgb — Pixels are stored in RED, GREEN, BLUE format, 24—bits per pixel 
(PIC_RGB_PACKED_PIXELS) 


rgba — Pixels are stored in RED, GREEN, BLUE, ALPHA format, 32~bits 
per pixel (PIC_RGBA_PACKED_PIXELS). 


agbr — Pixels are stored in ALPHA, GREEN, BLUE, RED format, 32—bits 
per pixel (PIC_AGBR_PACKED_PIXELS) 

Specifies from which segment of VRAM pixels should be saved (front is the 
default): 

front — Save pixels from the visible buffer of VRAM 

back — Save pixels from the invisible buffer of VRAM 


Print verbose output 


pictexture maps the current texture loaded into offscreen VRAM on a 1K by 1K polygon and 


displays it in the front buffer. 
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Overview of PIClib Functions 


The Pixel Machine’s graphics library, PIClib, consists of C-callable functions that allow you to 
create graphics primitives, curves, surface patches, transformations, texture maps, projections, 
zbuffering, Gouraud shading, double buffering, and anti-aliased lines and polygons and much more. 


The PIClib functions are grouped into the following categories: 


m= Control Functions — initialize and exit the graphics library; load PIClib program modules 
into the Pipes and Pixel Nodes; reset graphical parameters to default values; Transformation 
Pipes (multiple Pipe configurations); enable or disable the use of DSP32 floating point for- 
mat; and wait for vertical sync or Pixel Node processor sync. 


m Graphics Primitives — render objects with points, lines or filled polygons. These functions 
are categorized as follow: 


oO 


basic functions — render arcs and circles with specified precisions and rectangles. 
They also render lines and points (2D, 3D, 4D ), and move the current graphics posi- 
tion to a new point (2D, 3D, 4D ). 


polygon functions — define sequentially the vertices of a polygon in 2D, 3D, or 4D 
coordinates and close the polygon. These functions also allow normal vectors, rgb 
colors, and texture map indices to be attached to individual polygon vertices. 


quadric/superquadric functions — render spheres, hemispheres, cones, cylinders, 
ellipsoids, toroids, and hyperboloids of one or two sheets. 


curve and patch functions — render 3D curve segments and surface patches based on 
bicubic basis matrices. A basis matrix can be defined and saved. A basis matrix and a 
precision is selected before rendering the curve or patch. 


m Font and Character Functions — allow you to select a font type and display text using that 


font. 


m Transformation Functions — control the modeling and viewing transformations. These 
functions are categorized as follows: 


Q 


im] 


transformation control functions — store and retrieve transformation matrices 
to/from the transformation stack, get inverse transformation matrices, pre- or post- 
multiply the current transformation matrix with the specified matrix, and push or pop 
the transformation stack. Transformation control functions can operate on either the pro- 
jection transformation stack or the modeling/viewing transformation stack. 


modeling functions — translate, rotate and/or scale the geometric mode. These 
Operations may be done with absolute or incremental values. Modeling transformation 
functions can be applied to one coordinate axis or to all three simultaneously. 


viewing functions — define view points and view directions. A camera view can be 
defined in terms of pan, tilt, and swing angles. Look at and look up views can be 
defined in terms of a view point and a reference point. View points and view directions 
can be defined in polar coordinates. 
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O projection functions — define a 2D or 3D projection. The projection can be a 3D per- 
spective pyramid, a 3D perspective window, a 3D orthographic projection, or a 2D 
orthographic projection. 


Viewport Functions — specify a rectangular viewing space that becomes the active area of 
the screen. Using these functions, the viewport’s near and far boundaries are defined and 
retrieved. These definitions can be stored on the viewport stack along with their correspond- 
ing depth ranges. The viewport stack can be manipulated through push and pop operations. 


Shading and Depth Cueing Functions — select shading modes and light configurations 
and enable/disable depth cueing. The possible shading modes are flat, Gouraud and Phong. 
The light commands define light sources (direct, point, spot), set a light’s intensity value, and 
turn off/on any or all light sources. A surface shading model, such as ambient, diffuse, and 
specular coefficients can also be specified, as well as the object’s opacity and specular 
exponent. Enabling depth cueing causes points and lines to be rendered with intensities that 
vary as a function of depth. The z limits and boundary colors of depth cueing can be 
changed. 


a Color Functions — define the current rgb and alpha colors. These values are used for 


current color, point, line, polygon and clear screen commands. 


Display Functions — determine what modes of operation are in effect in the frame buffer 
and control certain aspects of the display. The different modes of operation are double 
buffering, overlays, anti-aliasing and alpha channel reading. Other display functions swap 
buffers; clear the rgb or alpha colors in the current viewport; define, draw and erase cursors; 
write or read a scan line of rgb pixels; and copy image/z buffer memory from on-screen to 
off-screen memory (and vice-versa). ; 


Hidden Surface Removal Functions — enable and disable the use of zbuffering and back- 
face surface removal algorithms. 


Video Functions —- control the updating of the video color maps. A complete rgb or alpha 
color map can be loaded, or one entry of the map can be loaded. The current color maps or 
a color entry can be retrieved from either the rgb map or the alpha map. 


a Raster Functions ~— perform logical operations on pixels, such as adds and multiplies. 


w Picking and Selecting Functions — can be used to identify objects on the screen based on 


the object’s coordinates. The picking and selecting functions can be enabled or disabled. 
Identifiers are maintained in a stack with load, push and pop commands. The size of the pick 
window or selection volume may be set. 


Input Device Functions — query for the current value of a locator or the current state of a 
mouse or keyboard button. These input device events can be queued or sampled. These 
functions also control the definition and display of cursors associated with a mouse. 
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a Compositing Functions — provide a full set of image compositing functions using the 
alpha channel of the image. 
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Control Functions 


The PIClib control functions perform operations that initialize and exit PIClib; reset graphical 
parameters to default values; swap Transformation Pipelines (dual Pipeline configuration); wait for a 
vertical sync, and wait for a Pixel Node sync. 


The control functions are: 


@ PICinit0) w PICresume() 

a PICdsp_float() m PICswap_pipe() 
& PICexit() m@ PICwait_vsync() 
a PICreset() g PICwait_psync() 
PICinit() 


PICinit() is usually the first graphics function call in every graphics program. The function initial- 
izes the viewport to a full screen (1024x1024 or 1280x1024 in high resolution mode, 720x480 in 
NTSC mode) and the transformation matrix to a 2D, full-screen, orthographic projection. PICinitQ 
also locks the Pixel Machine from other users, though it is still accessible to you from any windows 
you have open. 


PICinit( calls PICreset() to set all graphical parameters to default values. PICinit() also sets up 
a signal handler for the following signals: 


m@ hangup 
interrupt 
@ software termination. 


When invoked, the signal handler calls the PICexit() function and disconnects all forked processes, 
shared memories, and semaphores. 


The DEVtools automatic loading facility figures out what is loaded and what additional modules 
need to be loaded, therefore, the user does not have to remember what modules are already loaded 
into the Pixel Machine. This makes switching between libraries transparent. 


PICinit() returns an integer value of PIC_ERR_OK if the initialization is successful and should be 
called only once at the beginning of a program and before calling any PIClib functions. 
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om 


Example: 





finclude <pfciib-h> 


main () 


if (PICinit()) exit 1; 


PECexiti); 
exit (0)? 








PiCdsp _float() 


The PICdsp_float() function enables or disables DSP floating point format and can be used to send 
DSP floating point data into the Pixel Machine. When floating point format is enabled (mode = 
PIC_ON), floating point numbers on the host are assumed to be in DSP32 format and no conver- 
sion is made before downloading this data to the Pixel Machine. When floating point format is dis- 
abled (mode = PIC_OFF), floating point numbers on the host are assumed to be in IEEE format 
and are converted to DSP32 format after being downloaded. The default mode is PIC_OFF. 


PICdsp_float(mode) 
int mode; 


mode = PIC _ONor PIC_OFF 


PICexit() 


The PICexit() function halts all Transformation and Pixel Nodes and closes the device. If the exit is 
successful, PICexit() returns an integer value of PIC_ERR_OK. This function is always the last 
graphics function in an application program, and unlocks the Pixel Machine making it accessible to 
other users. 
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Example: 

















PiCreset() 


The PICreset() function resets all possible graphical parameters to their default values as follows: 








Function Default 
PICalpha() PIC_OFF 
PICantialias lines() PIC_OFF 
PICarc_precision() PIC_ARC_DEFAULT 
PICbackface() PIC_OFF 
PiCcircle_precision() PIC_CIRCLE_DEFAULT 
PICclockwise() PIC_OFF 
PICcolor_alpha() 0 
PICcolor_rgbQ) PIC_WHITE 


PICcomposite_mode() 
PICcurve_precision() 
PiCdefine_cursor() 
PICdepth_cue() 
PICdepth_cue_limits() 
PICdisplay_cursor() 


3-6 


PIC_NO_ COMPOSITE 
PIC_CURVE_DEFAULT 

mouse 

PIC_OFF 
PIC_ZMIN_DEFAULT,PIC_WHITE,PIC_ZMAX_DEFAULT,PIC_WHITE 
PIC_OFF 
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ee 


PICdisplay_overlay0 
PICdouble_buffer() 
PICdsp_float() 
PiCeuclid_mode() 
PICflipO 
PIClight_ambient() 
PICopen_vector_font() 
PICortho_2d_project0) 
PICpatch_precision() 
PICpercent_texture() 
PICput_alpha_map_entry() 
PICput_depth0 
PICput_picking region0 
PICput_rotate_dx() 
PICput_rotate_dy() 
PICput_rotate_dz() 
PICput_viewport() 
PICquadric_precision() 
PICselect_curve_basis() 
PICselect_patch_basis() 
PICshade_mode() 
PICupdate_map() 


PICzbuffer() 
PICzbuffer_lines() 
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PIC_OFF 

PIC_OFF 

PIC_OFF 

PIC_EUCLID_LINE 

PIC_OFF 

PIC_WHITE 

standard1 

full screen 

PIC_PATCH_ DEFAULT, PIC_PATCH_DEFAULT 
0.7 

[128 - 255], PIC_WHITE 
PIC_ZMIN_DEFAULT,PIC_ZMAX_DEFAULT 
8, 8 

0.0 

0.0 

0.0 

full screen 

PIC_QUADRIC_DEFAULT, PIC_QUADRIC_DEFAULT 
PIC_BEZIER_BASIS 
PIC_BEZIER_BASIS,PIC_BEZIER_BASIS 
PIC_SHADE_OFF 


PIC_OFF (if NTSC mode) 
PIC_ON (if high resolution mode) 


PIC_OFF 
PIC_OFF 


Contro! Functions 








PiCresume() 


The PICresume() function initializes PIClib without resetting any graphical parameters. 
PICresume() functions as PICinit() without calling PICreset() and is called once at the beginning 
of a PIClib program. 


PICresume() returns PIC_ERR_OK if the initialization succeeded. 


PiCswap pipe() 
The PICswap_pipe() function swaps the two Transformation Pipelines. This function operates only 
in systems with parallel dual Pipeline configurations. By enabling the user to route commands to 


different Pipelines, this function helps to optimize program performance by allowing for the simul- 
taneous generation and transformation of various objects. 


PilCwait_vsync() 

The PICwait_vsync() function waits for a video vertical sync before executing the next graphics 
function. 

PiCwait_psync() 

The PICwait_psync() function waits for all Pixel Node processors to sync on the same instruction 


before continuing. This function is used by PICexit() before halting the Transformation and Pixel 
Nodes. 
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The Basic graphics primitives functions let you render points, lines, arcs, circles, and rectangles. 
They also allow you to specify the drawing precision used to generate arcs and circles (i.e., you can 
define the number of points, lines, or filled polygons to be used in rendering an arc or circle); 
specify the drawing mode (point, line, or polygon); move the current drawing position. 


The Basic functions described in this section are as follows: 


mw PICeuclid_mode(mode) = PICmove_3d(x,y,z) 

m PICarc(x,y,1,start,end) = PICmove_4d(x,y,z,w) 

m PICcircle_precision(n) w PICimove_2d(ix,iy) 

w PICrectangle(x0,y0,x1,y1) a PICimove_3d(ix,iy,iz) 

m PICdraw_2d(x,y) m PICimove_4d(ix,iy,iz,iw) 
m= PICdraw_3d(x,y,z) w PICpoint_2d(x,y) 

m PiCdraw_4d(x,y,z,w) m PICpoint_3d(x,y,z) 

m PICidraw_2d(ix,iy) m PICpoint_4d(x,y,z,w) 

= PiCidraw_3d(ix,iy,iz) g PICipoint_2d(ix,iy) 

w PICidraw_4d(ix,iy,iz,iw) w PICipoint_3d(ix,iy,iz) 

= PICmove_2d(x,y) w PICipoint_4d(ix,iy,iz,iw) 


PiCeuclid_mode() 


The PiCeuclid_mode() function sets the drawing mode for generating arcs, circles, rectangles, 
polygons, curves, patches, quadrics, and superquadrics. The default drawing mode is 
PIC_EUCLID_LINE. Available modes are: 


PIC_EUCLID_POLYGON 
PIC_EUCLID_TEXTURE 















Overview of PIClib Functions 3-9 


Graphics Primitives — Basic Functions 





PICeuclid_mode(mode) 


int mode; 
mode = PIC EUCLID POINT 

PIC_EUCLID LINE 

PIC_EUCLID POLYGON 

PIC_EUCLID_TEXTURE (currently used only for rendering bicubic patches) 
PICarc() 


The PICarc() command draws a circular arc in the xy plane, at z = 0, using the current attributes. 
The arc is generated according to the mode specified by PICeuclid_mode(). 


To draw an arc, you must specify the coordinates (x,y) of the arc’s center; the radius of the arc, 7; 
and the starting and ending angles, start and end. The angles are measured from the positive x axis 
and are specified in positive floating point degrees. The arc is rendered counterclockwise from the 
start angle to the end angle. 


The number of points, lines, or polygons used in rendering the arc is set by the PICare | precision() 
function. 





PICarc(x,y,1,start,end) 

float x,y,1,start,end; 

XY = the x,y coordinates of the arc’s center point 
r = the arc’s radius 

start = the arc’s starting angle measured in degrees 
end = _ the arc’s ending angle measured in degrees 
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Example: 


The following program renders an arc in the positive x,y quadrant. The arc has a center point of 
200.0,200.0, a radius of 100, a starting angle of 0.0, and an ending angle of 90.0. The arc is red 
(specified by the PICcolor_rgb() function). By default, the drawing mode is set to 
PIC_EUCLID_LINE and, therefore, the arc is composed of line segments. 





PiCarc_precision() 


The PICarc_precision() function is used to set the precision at which the arc will be drawn. The 
number of points, lines, or polygons used in rendering the arc is specified by the argument, n. The 
larger n is, the smoother the arc will be. The default value for n is PIC_ARC_DEFAULT. 


PICarc_precision(n) 
int n; 


Overview of PiClib Functions 3-11 


Graphics Primitives —- Basic Functions 





n = __ the number of points, lines, or polygons used in rendering the arc 





Example: 


The following program is the same as the one shown for rendering an arc. This time, however, the 
arc’s precision is set at 100, which results in a smoother arc. 





/*render an are*/ 


#include <piciib.h> 


main (} 
{ 


Lf (PICinit(}} “exit: (Ey; 


/*clear the screen to bhie*/ 


Piccolor rgb{0:.0,0.0,1.0) 3 
Picclear_rgb(}.; 


/*select red drawing. color*/ 
PiCcolor_rgb{1.0,0.0,0.0); 
/*set arc precision*/ 


PICcare_precision {100}; : 
PICarc(200.0,200.0,.100:0;:0.0;90:0);7"° 
Picexit (); 

exit (0); 





PiCcircle() 
The PiCcircle() function draws a circle in the xy plane at z = 0, using the current attributes. The 
circle is generated according to the mode specified by PICeuclid_mode(). 


To draw a circle, you need to specify the circle’s center point (x,y) and its radius, 7. The circle’s 
precision is set by the PICcircle_precision() function. 





PICcircle(x,y,r) 
float x,y,t; 
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the x,y coordinates of the circle’s center point 


Es 
SJ 
i 


r = _ the circle’s radius 





Example: 


The following program renders a red circle with a center point of 200.0,200.0 and a radius of 100.0. 
Since the circle’s precision is not specified, the default setting of PIC_CIRCLE_DEFAULT line 
segments will be used. 
















/*render a red circle*/ 
#include <piclib.n> 
main () 
4 
LE (PICinit()) exit (1); 
/*clear the screen to bluet/ 


PICcolor_rgb(0.0,0.0,1.0); 
PICclear_rgb{); 


/*select red drawing color*/ 


PICcolor_rgb(1.0,0.0,0.0); 
PICccircle (200.0, 200.0,100.0);-- 
PICexit (); 

exit (0); 





PiCcircle_precision() 


The PICcircle_precision() function is used to set the precision at which a circle will be rendered. , 
The number of points, lines, or polygons used in rendering the circle is specified by the argument, 
n. The larger n is, the smoother the circle will be. The default value for n is 
PIC_CIRCLE_DEFAULT 





PICcircle_precision(n) 
int n; 
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n = __ specifies the number of points, lines, or polygons used to render the 
circle 
Example: 


The following program is the same as the one shown for rendering a circle. This time, however, the 
precision is set to 100, which results in a smoother circle. 


~petender-a red: clxéle*/ 


Pginelude  <piclip.i © 


tO) exit yy: 


“s@reen to bluet/ 





PiCrectangle() 


The PICrectangle() function renders a rectangle in the xy plane, at z = 0, using the current attri- 
butes. The rectangle is generated according to the mode specified by PICeuclid_mode(). 


To render a rectangle, you must specify its lower left corner (x0,y0) and its upper right corner 
(x1,y1). The sides of the rectangle are parallel with the x and y axes of the coordinate system. In 
line mode, the current graphics position is (x0,y0) after the rectangle is drawn. 





PICrectangle(x0,y0,x1,y1) 
float x0,y0,xLy1; 
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x0,yO = define the lower left corner of the rectangle 


define the upper right corner of the rectangle 


i 


x1Ly1 





Example: 


In the following example, the drawing mode is set to PIC_EUCLID_POLYGON. The lower left 
and upper right corners of the rectangle are defined as 400. 1.0, 300.0 and 800.0, 500.0, respectively. 


~“fecender a green rectangle*/ 
“#indlude _ <piclib. b> 
ain hs 2 
ee ee ieee ee 
oa ALS (PICIinit ()) exit (Lye: 


“Pelear: séreen ‘to: white*/ 


oe viceo or rgb (1.0,1-0,4.0)7 


slor gb (1.0,0.0/0.0)7 
- Piselect’ drawing: mode*/ a 
“ PECevelid’ mode: (PIC BUCLID POLYGON): ae 
 Preender. rectangle*/" 
oR rectangle (400. 6, 1300. 0, 800. 





PiCdraw() 


The PICdraw functions draw a line from the current graphics position to the given point using the 
current attributes. There are six PICdraw functions: 
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mw PICdraw_2d(x,y) mw PICidraw_2d(ix,iy) 
g PICdraw_3d(x,y,z) a PICidraw 3d(ix,iy,iz) 
m PICdraw_4d(x,y,z,w) & PICidraw_4d(ix,iy,iz,iw) 


PICdraw_4d() uses homogeneous coordinates to draw a 3D line from the current graphics position 
to the point represented in 3-space as (x/w, y/w, z/w). If w =1, the homogeneous coordinates 
represent the physical coordinates (x, y, 2). 


PICdraw_2d(x,y) 
float x,y; 


XV = the x and y floating point coordinates of the 2D point to which the 
line is drawn 

PICidraw_2d(ix,iy) 

int ix,iy; 


ix,iy = the ix and iy integer coordinates of the 2D point, to which the line is 
drawn 


PICdraw_3d(x,y,z) 
float x,y,z; 


X/V/Z = the x,y, and z floating point coordinates of the 3D point to which the 
line is drawn 

PICidraw_3d(ix,iy,iz) 

int ix,iy,ix; 

ix, iy, iz = the ix, iy, and iz integer coordinates of the 3D point to which the line 
is drawn 

PICdraw_4d(x,y,z,w) 

float x,y,z,;w; 

XV /Z,W = the x, y, z, and w floating point coordinates of the 4D point to which 
the line is drawn 


PICidraw_4d(ix,iy,iz,iw) 
int ix,iy,iz,iw; 
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ix,iy,iziiw = _ the ix, iy, iz, and iw floating point coordinates of the 4D point to 
which the line is drawn 


PiCmove() 


The PICmove functions move the current drawing position to a specified one. There are six PIC- 
move functions: 


a PICmove_2d(x,y) a PICimove_2d(ix,iy) 
g PICmove_3d(x,y,z) gs PICimove_3d(ix,iy,iz) 
m PICmove_4d(x,y,z,w) a PICimove_4d(ix,iy,iz,iw) 


PICmove_4d() changes the current graphics position to the 3D point (x/w,y/w,z/w). If w = 1, the 
homogeneous coordinates of this point represent the physical coordinates (x,y,z). 


PICmove_2d(x,y) 
float x,y; 


XY = the x andy floating point coordinates of the 2D point 


PICimove_2d(ix,iy) 
int ix,iy; 


ix,iy = the x and y integer coordinates of the 2D point 
PICmove_3d(x,y,z) 

float x,y,z; 

KZ = the x,y, and z floating point coordinates of the 3D point 


PICimove_3d(ix,iy,iz) 
int ix,iy,iz; 
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ix,iy,iz = the x, y, and z integer coordinates of the 3D point 


PICmove_4d(x,y,z,w) 
float x,y,z,w; 


X/Y/Z/W = the x, y, z, and w floating point coordinates of the 4D point 
PICimove_4d(ix,iy,iz,iw) 
int ix,iy,iz,iw; 


ix,iy,izjiw = the x, y, z, and w integer coordinates of the 4D point 


PiICpoint() 


The PICpoint function(s) draw a point at a specified location, defined by the coordinates, using the 
current color. 


The PICpoint functions are: 


w PICpoint_2d(x,y) a PICipoint_2d(ix,iy) 
w@ PICpoint_3d(x,y,z) a PICipoint_3d(ix,iy,iz) 
m PICpoint_4d(x,y,z,w) g PICipoint_4d(ix,iy,iz,iw) 


The PICpoint_4d() function draws a point the size of a pixel at location (x/w,y/w,z/w). If w = 1, 
the physical coordinates of this point are the same as the homogeneous coordinates (x,y,2,w). If w 
= 0, the homogeneous point represents a point at infinity and the new graphics position becomes the 
point (x/w,y/w,z/w). 


PICpoint_2d(x,y) 
float x,y; 


xY = the x and y floating point coordinates of the 2D point 


PICipoint_2d(ix,iy) 
int ix,iy; 
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ix,iy = the x and y integer coordinates of the 2D point 


PICpoint_3d(x,y,z) 
float x,y,z; 


XYZ = the x, y, and z floating point coordinates of the 3D point 
PICipoint_3d(ix,iy,iz) 

int ix,iy,iz; 

ix,iy,iz = the x, y, and z integer coordinates of the 3D point 


PICpoint_4d(x,y,z,w) 
float x,y,Z,wW; 


X,Y /,Z,W = the x, y, z, and w floating point coordinates of the 4D point 
PICipoint_4d(ix,iz,iy,iw) 
int ix,iz,iy,iw; 


ix,iz,iy,jiw = the x, y, z, and w integer coordinates of the 4D point 
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The Polygon functions let you render 2D, 3D, or 4D polygons by defining a sequence of coordinates 
and then closing the polygon. These functions also allow normal vectors, rgb colors, and texture 
map indices to be attached to individual polygon vertices. 


The maximum number of points in a polygon is defined in the PIC_MAX_POINTS constant. After 
all vertices have been specified, the PICpoly_close() function must be called to close the polygon 
by connecting the last polygon vertex to the first polygon vertex. 


The functions described in this section are: 


w PICclockwise(mode) mw PICpoly_point_4d(x,y,z,w) 

= PICpoly close() m= PiCpoly_point_nv(x,y,z,nx,ny,nz) 

a PICpoly_normal(nx,ny,nz) a PICpoly_point_uv(x,y,z,u,v) 
 PICpoly_point_2d(x,y) a PICpoly_point_rgb(x,y,z,1,g,b) 

g PICpoly point _3d(x,y,z) a PICpoly point_nv_uv(x,y,z,nx,ny,nz,u,v) 
PiCclockwise() 


The PICclockwise() function defines how a normal vector of a polygon is computed. The calcu- 
lation of the normal vector affects backface removal and normal shading. The first three vertices 


(Pg, Py, P.) of a polygon are used to form two vectors. When this function is set to PIC_ON, the 
normal vector is computed as 


When this function is set to PIC_OFF, the normal vector is computed as 
N = (Pg ~ Py) x P, - Pp) 


The default mode is counterclockwise. 


The direction of the vector is defined by the right-hand rule. 
NOTE 
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PICclockwise(mode) 
int mode; 
mode =  PIC_ONor PIC_OFF 


PiCpoly_ close() 


The PICpoly_close() function closes a polygon by connecting the last polygon vertex to the first 
polygon vertex. 


ore This function must be used after a sequence of PICpoly_point functions. 
NOTE 


PICpoly_close() 


PiCpoly_normal() 


The PICpoly_normal() function is used to define a surface normal (nx, ny, nz) for a polygon. 
The surface normal should point outward in closed solid objects and is used for backface culling, 
flip tests and flat shading. PICpoly_normal() has to be specified before the corresponding 
PIiCpoly_point functions. The surface normal does not need to be normalized. 


ore This function must be specified before the corresponding PICpoly_point commands. 
NOTE 


PICpoly_normal (nx, ny, nz) 


float nx, ny, nz; 
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nx, ny,nz = normal vector 





PiCpoly_point() 


The PICpoly_point functions are used in a sequence to render 2D, 3D, or 4D polygons. The 
sequence of coordinates defined by each call to a PICpoly_point function are not connected until 
the PICpoly_close() function is invoked. The polygon is rendered using the current attributes. If 
shading is disabled, the specified polygon is rendered using the current color. 


The PICpoly_point functions are: 


 PICpoly_point_2d(x,y) 

#8 PICpoly_point_3d(x,y,z) 

a PICpoly_point_4d(x,y,z,w) 

The PICpoly_point_3d(x,y,z) function operates in each shading mode as follows: 


@ If shading is disabled, then the current color (specified with PICcolor_rgb) is used to fill the 
polygon. 


m If flat shading is enabled and a user-specified normal vector (PICpoly_normal()) precedes 
the definition of the polygon points, then that definition is used to compute the shade of the 
polygon. If a normal vector for the polygon is not specified, then a normal vector for the 
polygon is computed in the Transformation Pipeline. (The points must be in counterclockwise 
order to obtain an outward-pointing normal vector unless PICclockwise(PIC_ON) has been 
called; this vector is then used to compute the shade of the polygon.) 


m If Gouraud or Phong shading is enabled, the normal vector to the polygon is computed in the 
Transformation Pipeline and copied to each vertex for use in shading. 





PICpoly point_2d(x,y) 
float x,y; 
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XY = the x, y coordinates of the 2D polygon point (z = 0.0) 


PICpoly_point_3d(x,y,z) 
float x,y,z; 


XYZ = the x, y, and z coordinates of the 3D polygon point 


PICpoly_point_4d(x,y,z,w) 
float x,y,Z,W; 


XY /Z,W = the x, y, z, and w coordinates of the 4D polygon point 


It is recommended that polygons be planar and convex. Currently, there is a limit of 
PIC_MAX_ POLY _PNTS points per polygon. 





Example: 


The following program fragment illustrates the commands used to render 2D and 3D polygons. 
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PiCpoly point_nv() 


ThePICpoly_point_nv() function is used in a sequence to draw a 3D polygon with a normal (nx, 

ny, nz) defined at each polygon vertex (x, y, z). The vertex normal should point outward in closed 
solid objects and is used by the Gouraud shading routines {it is ignored by flat shading routines), A 
sequence of PICpoly_point_nv() function calls must be followed by a PICpoly_close() function. 


This function operates as follows in each shading mode: 


m If shading is disabled, then the current color (specified with PICcolor_rgb(Q) is used to fill 
the polygon. 


@ If flat shading is enabled, then the normal vector (nx,ny,nz) specified at each vertex is 
ignored. If a user-specified normal vector (PICpoly_ normal()) precedes the definition of 
the polygon points, then it is used to compute the shade of the polygon. If a normal vector is 
not specified, then a normal vector is computed in the Transformation Pipeline. (The points 
must be in counterclockwise order to obtain an outward-pointing normal vector unless 
PICclockwise(PIC_ON) has been called; this vector is used to compute the shade of the 
polygon.) 


a If Gouraud shading is enabled, the normal vector (nx,ny,nz) is used to compute an rgb inten- 
Sity at each vertex. 


m If Phong shading is enabled, the vertex and its normal vector are sent to the pixel nodes for 
shading. 





PICpoly_point_nv(x,y,z,nx,ny,nz) 
float x,y,z nx,ny,nz; 


XV /Z = the x, y, and z coordinates of the 3D point 


nxny,nz = normal vector 





PIC_MAX_POLY_PNTS points per polygon. The vertex normals do not need to be nor- 


It is recommended that polygons be planar and convex. Currently, there is a limit of 
NOTE 
malized. 
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PICpoly point _uv() 


PICpoly_point_uv() is used in a sequence to render a 3D polygon with a texture index (u,v) 
defined at each polygon vertex (x,y,z). The intensity of each pixel is a combination of the texture 
value and the shading value. The combination of these values can be set with 
PICpercent_texture(). 


A sequence of PICpoly_point_uv() functions must be followed by a PICpoly_close() function. 


void PICpoly_point_uv(x, y, z, u, v) 
float x, y, Z, U, V; 


Xy,Z = the x, y, and z coordinates of the 3D point 


u,v = _ texture index 


Itis recommended that polygons be planar and convex. Currently, there is a limit 
of PIC_MAX_POLY PNTS points per polygon. 


Polygons rendered with this function are flat shaded. 


PiCpoly_point_rgb() 


The PICpoly_point_rgb() function is used in a sequence to draw a 3D polygon with a rgb color 
(r, , b) defined at each polygon vertex point (x, y, z). Each r, g, and b color parameter can range 
from 0.0 to 1.0, A sequence of PICpoly_point_rgb() functions must be followed by a 
PICpoly_close() function. 


This function operates as follows in each shading mode: 


m If shading is disabled, then the rgb color is used to color each vertex. (The vertex colors are 
interpolated over the polygon.) 


m If flat shading is enabled, then the color at each vertex (7,2,b) is ignored. If a user-specified 
normal vector precedes the definition of the polygon points, then it is used to compute the 
shade of the polygon. If a normal vector is not specified, then it is computed in the Transfor- 
mation Pipeline. (The points must be in counterclockwise order to obtain an outward-pointing 
normal vector unless PICclockwise(PIC_ON) has been called.) 
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@ If Gouraud or Phong shading is enabled, the normal vector to the polygon is computed in the 
Transformation Pipeline and copied to each vertex for shading. 





PICpoly_point_rgb(x,y,z,1,2,b) 
float x,y,z,1,g,b; 


x%y,z = the x, y, and z coordinates of the 3D vertex 


1g,b = the color at a polygon vertex, where each primary component is a 
floating point number in the range 0.0 to 1.0 (i.e., a normalized color) 


It is recommended that polygons be planar and convex. Currently, there is a limit of 
PIC_MAX_POLY_PNTS points per polygon. 





PiCpoly_ point_nv_uv() 
The PICpoly_point_nv_uv() function is used in sequence to render 3D polygon points with nor- 
mal vectors and texture indices. This function operates as follows in each shading mode: 


m If shading is disabled, then the current color (specified with PICcolor_rgb() is copied to 
each vertex, and the normal vector value (nx,ny,nz) is ignored. 


w If flat shading is enabled, the user-specified normal vector or Transformation Pipeline com- 
puted normal vector is used to compute a shade for the polygon. The normal vector at each 
vertex is ignored. 


@ If Gouraud shading is enabled, the normal vector is used to compute an rgb intensity at each 
vertex. The intensity at each pixel within the polygon is a combination of the texture map 
and the shading value. 


If Phong shading is enabled, the vertex, normal, and texture map indices are sent to the pixel 
nodes for shading. 


The intensity value at each pixel is computed according to the following equation: 


Intensitypixe =texture_percent*texture_color+(1.0 — texture percent )*surface_intensity 
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The value texture_percent can be set with the PICpercent_texture() function. 


When using perspective projection, objects composed of this type of polygon point 
should be tessellated into many small polygons to ensure minimal perspective distortion. 





PICpoly_point_nv_uv(,y,z,nx,ny,nz,u,v) 
float x,y,z,nx,NyNZ,U,v; 


XZ = the x, y, and z coordinates of the 3D point 
nxny,nz = normal vector 
u,v = texture map indices 





The u,v values are not restricted to the range [0.0,1.0]. Assigning values greater than 1.0 will 
repeat the texture map over the surface, while assigning values less than 1.0 will allow for the 
extraction of a portion of the texture map. 


It is recommended that polygons be planar and convex. Currently, there is a limit of 
PIC_MAX_POLY_PNTS points per polygon. The vertex normals do not need to be nor- 
malized. 
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The Quadrics and Superquadrics functions render cylinders, ellipsoids, toroids, and hyperboloids 
of one or two sheets. 


ore The maximum precision for superquadrics is limited to 160 divisions in each direction. 
NOTE 


The functions discussed in this section are: 


g@ PICquadric_precision(nu,nv) a PICsuperq_toroid(x,y,z,r,exp1,exp2) 
a PICsphere() m PICsuperq_hyper1(x,y,z,exp1,exp2) 
m PICsuperq _ellipsoid(x,y,z,exp1,exp2) @ PICsuperq_hyper2(x,y,z,exp1,exp2) 


PiCquadric_precision() 


The PICquadric_precision() function sets the precision used to render quadrics and superquadrics. 
The precision is defined by the number of line segments (or points) used to approximate the quadric 
in both the u and v directions. If the values for either direction is less than zero, the function returns 
a value of PIC_ERR_ARG. The default is 16x16. 





PICquadric_precision(nu,nv) 
int nu,nv; 


nu = __ the number of line segments (or points) used to approximate the qua- 
dric in the u direction 


nv = __ the number of line segments (or points) used to approximate the qua- 
dric in the v direction 
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PiCsphere() 


The PICsphere() function renders a sphere using the current color and drawing mode (i.¢., point, 
line, or polygon). The sphere is centered at the current graphics position and has a unit radius. Its 
precision is set by the PICquadric_precision() function. 


If polygon mode is on, the sphere is shaded according to the current shading mode. 


PICsphere() 


PiCsuperq ellipsoid() 


The PICsuperq ellipsoid() function renders a superquadric ellipsoid using the current attributes. 
A superquadric ellipsoid is a single, closed volume that ranges from a cuboid to a spheroid to a 
pinched object, depending on the specified exponents, and is represented mathematically as follows: 


pin, 0) = | yeoseriapsiner2(0) 
: Zsin@P icy 

where, 7 and w are the longitudinal and latitudinal angles, respectively. 

Values for 7 are in the range: -pi/2 <= n <= pi/2. 

Values for @ are in the range: -pi <= @ < pi. 

The shape of the ellipsoid can be modified by varying the exponents as follows: 


exp<i1  Square-shaped ellipsoids 
exp=1 Round ellipsoids 
exp=2  Flat-beveled ellipsoids 
exp>2 Pinched ellipsoids 


If polygon mode is on, the ellipsoid is shaded according to the current shading mode. 


PICsuperq_ellipsoid(x,y,z,exp1,exp2) 
float x,y,z,exp1,exp2; 
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Xy,Z = the radii of the ellipsoid in the x, y, and z directions 
expl = _ the squareness parameter in the longitudinal direction 
exp2 = __ the squareness parameter in the latitudinal direction 


Make sure all arguments specified for this function are greater than or equal to zero. 





Example: 


The following program fragments render a sphere, ellipsoid, cube, and cylinder, respectively: 
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PiCsuperq _toroid() 


The PICsuperq_toroid() function renders a superquadric toroid using the current attributes. The 
toroid is represented mathematically as follows: 


x + ia cos®P2(a) 


,@)= a + coseP! sin’? 2(w) 
BO O= yoy 


where, 


and where 1) and @ are the longitudinal and latitudinal angles, respectively. 
Values for n are in the range: -pi <= TN < pi. 
Values for @ are in the range: -pi <= @ < pi. 


If x and y parameters are not the same, the toroid radius is "stretched" in the direction of the larger 
parameter. The shape of the toroid can be modified in each direction by varying the exponents as 
follows: 


exp<1  Square-shaped toroids 
exp=1 _ Round toroids 
exp=2  Flat-beveled toroids 
exp>2 Pinched toroids 


If polygon mode is on, the toroid is shaded according to the current shading mode. 


PICsuperq_toroid(x,y,z,1,exp1,exp2) 
float x,y,z,1,exp1,exp2; 


“yz = the radii of the toroid ring 

ro = the distance from the center of the torus to the center of the outer 
ring (see Figure 3-1) , 

expl = __ the squareness parameter in the longitudinal direction 

exp2 = __ the squareness parameter in the latitudinal direction 
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Figure 3-1: A Superquadric Toroid 








PiCsuperq_hyper1() 


The PICsupergq_hyperi() function renders a superquadric hyperboloid of one sheet using the 
current attributes. e hyperboloid is represented mathematically as follows: 


xsecor! a COs’? 2(@y) 
pM, @) = | ysec*P!(1y)sineP2(w) 
Ztan?Pl(7y 


where, 7| and © are the longitudinal and latitudinal angles, respectively. 
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Values for 7 are in the range: -pi/2 < nq < pi/2. 

Values for @ are in the range: -pi <= @ < pi. 

If polygon mode is on, the hyperboloid is shaded according to the current shading mode. 
The shape of the hyperboloid can be modified by varying the exponents as follows: 


exp < l Square-shaped hyperboloids 
exp = lL Round hyperboloids 

exp = 2 Flat-beveled hyperboloids 
exp > 2 Pinched hyperboloids 


PiCsuperq hyperl(x,y,z,exp1,exp2) 
float x,y,z,expLexp2; 


XW = the radii of the xy cross-section of the hyperboloid at z = 0 
Zz = the height of the hyperboloid when 7n = 45° 

expil = __ the squareness parameter in the longitudinal direction 

exp2 = _ the squareness parameter in the latitudinal direction 


PiCsuperq_hyper2() 


The PICsuperq_hyper2() function renders a superquadric hyperboloid of two sheets using the 
current attributes. The hyperboloid is represented mathematically as follows: 


vino) | pea eats 


ePi(ny 
where, 1) and @ are the longitudinal and latitudinal angles, respectively. 


Values for 7 are in the range: -pi/2 < n < pi/2. 
Values for @ are in the range: -pi/2 <  < pi/2 (piece 1), pi/2 < w < 3*pi/2 (piece 2) 


The shape of the hyperboloid can be modified by varying the exponents as follows: 


exp < 1 Square-shaped hyperboloids 
exp ~ 1 Round hyperboloids 

exp = 2 Flat-beveled hyperboloids 
exp > 2 Pinched hyperboloids 
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PICsuperq hyper2(x,y,z,exp1,exp2) 
float x,y,z,t,exp1,exp2; 


XY = the radii of the xy cross-section of the hyperboloid at z = 0 
Zz = the height of the hyperboloid when ny = 45° 

exp1 = the squareness parameters in the longitudinal direction 
exp2 = __ the squareness parameters in the latitudinal direction 





3-34 PIClib User’s Guide, Version 1.2 





Graphics Primitives — Curve Functions 


The Curve functions generate parametric curves which can be displayed as a set of points or con- 
nected line segments. A parametric curve is a set of points obtained by interpolating or approxi- 
mating a set of control points. The coordinates of the points that define a parametric curve are of 
the form 

=x(u) y=ylu) z= 2(u) 
where u is a parametric variable with an interval of u € [0,1]. 
In PIClib, curves are rendered by first specifying a basis matrix and then defining a set of four 3D 
control points that determine the shape of the curve. The basis matrix determines how the control 


points will be used to render the curve. Complex curves are rendered by connecting several curve 
segments to form one curve. However, care must be taken at curve boundaries to ensure continuity. 


For more information on ensuring the continuity of a curve, refer to Mathematical Elements for 
Computer Graphics by David F. Rogers and J. Alan Adams (1976, McGraw-Hill, Inc.) or Geometric 
Modeling by Michael E. Mortenson (1985, John Wiley & Sons, Inc.). 


The Curve functions described in this section are: 


# PICcurve geometry _3d() 
# PiCcurve_precision() 
a PICput_basis() 


w PICselect_curve_basis() 


Generating Curves 


PiClib offers basis matrices for four predefined classes of curves; Bezier Curves, Hermite 
Curves, Four-Point Curves and B-Spline Curves. Each curve is cubic (third order polynomial) 
and generated using the method of forward differences. More complicated curves can be con- 
structed from several smaller curves. Each of the predefined classes of curves is described below. 


To define basis matrices for other classes of curves, use the PICput_basis() function discussed 
later in this section. 


Bezier Curves 


A Bezier curve defines the position of the curve’s end points and uses two other points (not on the 
curve) to define indirectly the tangents at the curve’s end points. Bezier curves are defined with a 
set of four control points (p Py ,Po> and P3) representing the vertices of a polygon. Each point (p) 
consists of the components Geyey The tangent at Po is P} - Po and the tangent at P3 is Po - P- 
The curve always passes through Po and P3. 
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The control points can be easily manipulated to change the shape of the curve as desired. (Any 
local changes are strongly propagated throughout the entire curve.) For example, by specifying the 
first and last control points to the same position, a closed curve is generated. The control points 
define a convex polygon called a convex hull, which bounds the Bezier curve and ensures that it 
follows specified control points. The matrix for this type of curve is: 


Xo X1 X2 X3 


0 21 8B 


Hermite Curves 


A Hermite curve is a cubic curve. The left half of the input curve matrix is filled with the end 
points of the curve Po and Py The right half is filled with tangent vectors at the end points of the 
curve Po” and p, - A Hermite curve always passes through the end points (interpolates) and 
approximates the two inner points. The matrix is as follows: 


Xo X1 Xb X 


pul ny 


B-spline Curves 


A B-spline curve is a class of spline curves that approximates the end points, allowing both the 
first and second derivatives to be continuous at the segment’s end points. This type of curve uses a 
set of blending functions to allow localized changes to be made easily by manipulating only a few 
neighboring control points. No part of the curve passes through the control points. 


Local changes are propagated only in the area of change. For example, if you change the position 
of the first control point, the shape of the curve changes near the first point without significantly 
affecting the rest of the curve. 


Four-point Curves 


A Four-point curve is an interpolating curve that passes through four distinct points in space. The 
control points (PpP 1 P, and p,) are assigned the parametric u values 0, 1/3, 2/3, and 1, respec- 
tively. This type of curve is cubic (third order polynomial). 
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PiCcurve geometry _3d() 


The PICcurve geometry _3d() function renders a 3D curve using the current curve precision, 
color, and drawing mode. The curve is rendered using the current color. 





PICcurve_geometry_3d(geom) 
float geom(3][4]; 


geom = _ a set of four 3D control points that determine the shape of the curve 


PiCcurve_precision() 


The PICcurve_ precision() function specifies the number of points, lines, or polygons used in 
rendering the curve. The precision is expressed as a positive integer between 4 and infinity. The 
higher the precision specified, the smoother the curve that is rendered. 


PICcurve_precision(n) 
int n; 
n = the number of points or lines used to render the curve 


PiCput_basis() 


The PICput_basis() function defines a 4x4 basis matrix and an associated index number, which 
can subsequently be used in rendering curves. The index numbers are defined by the following con- 
stants: 


PIC_USER_BASIS_0 
PIC_USER_ BASIS _1 








PIC USER BASIS 7 
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At initialization, the first four basis matrices contain the matrix definitions for Bezier curves, Her- 
mite curves, Four-point curves and B-spline curves respectively. Unless you wish to overwrite 
these matrices, the index argument passed to PICput_basis() should range from 
PIC_USER_BASIS_4 to PIC_MAX_BASIS. 


If index is less than zero or greater than or equal to PIC_MAX_BASIS, this function returns a value 
of PIC_ERR_ARG. 


Once defined, the basis matrix is selected by passing its associated index to the 
PICselect_curve_basis() function. 


PICput_basis(basis,index) 
PICmatrix basis; 


int index; 
basis = an matrix of 16 floating point numbers 
index = the index number associated with the basis matrix 


PiCselect_curve_basis() 


The PICselect_curve_basis() function selects the basis matrix that is used to render curves. (The 
matrix and its index are defined with the PICput_basis() function.) Make sure the matrix and its 
index are defined before using the PICselect_basis() function. If index is less than zero or greater 
than or equal to PIC_MAX_BASIS, this function returns a value of PIC_ERR_ARG. 


PICselect_curve_basis(index) 
int index; 


index = the index to the basis matrix 





Example: 


The following program defines the x, y, and z coordinates of the control polygon for a bicubic 
curve, sets the precision in u and v direction, selects basis PIC_BEZIER_BASIS; draws the control 
polygon; and, finally, generates a Bezier curve. 
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/* define x,y and z coordinates of the control polygon for a bicubic curve 


defined as ; 





XO XL X2 X3 
YO. Y1 ¥2.¥3 
: 20.2% 22 23 
af 
PICmatrix Ge{ 
wore : : 100.0, 100.0, 0.0, 0.0, 
0:0,.0.0, 100.0, 100.0, 
0.0,°100.:0, 100.0, 0.0, 
he 


maintarge, argv) 


int: “ALGC; - 
“J ehar po #earguy 
oa : 
int npixl, nline; 
z dnt precu, precy; 
ae : “int basis? 
Osi “4, iter; 





df (PFCinit:() } exit (-1); 





y* “animate -*/ 
PICdouble buffer (PIC -ON); 


“PICget.screen:.size( enpixl, enline:); 
“PICput_Viewport ( 0, nptxl-1, 0," nline-1. )} 








eh PICcopy_f ront. to. back ()j 


/* make. drop shadow. */) 





PICput_viewport ( 290420, 990+20; 80420, 800420: ); 
PiCpixel add{ 0:52), -O2:2). -0,2,.°+0.2°):7 
PICswap buffer (); 


PICput_viewport ( 290420; 990+20, 80+20,. 800420); 
PICpixel .add{. -0.2, -0.2,.-0.2,; 40:2.) 
PiIcswap_ buffer (}7: tes i 


/* create viewport and projection */ 


PICput_viewport (290, 990, 80,° 800°}; 
PICput. depth( 0:0, 32767.0.); 


L CS 


(continued on next page ) 
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/* set viewing and projection: par 


PiCpersp project (45.0. ,.1.25,21.0,. 2 
PiClookup_view(1%50.0, 150.0,. 150: 





7#* set precision inl direction, v-dtrectio 
select basis index 0 (bezier basis}. */ 


precu = 25; 
basis = 07 











PiCcurve precision (precy). 
PICselect._curve_basis (basis 
PIceucltd_mode{PiC_EUCLID LINE) 





#* rotate curve arotind the'z 
iter = 550; 


do { 


/* draw some.:axes 


(continued on next page ) 


3-40 PiClib User’s Guide, Version 1.2 





Graphics Primitives - Curve Functions 





/* generate’ a Bezier curve */ 


piCcurve geometxy. 
pI¢swap buffer tp 





} while (iter==); 


Picexit ()7 
exit ()7 
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A patch is a bounded collection of points and is the simplest mathematical element used to model a 
surface. The coordinates of the points that define the patch have two parameters and are of the 
form: 


x=x(uw) y=yluw) z= 2z(u,w) 
where u and w are parametric variables with an interval of u,w € [0,1]. 


In PIClib patches are rendered by first specifying a basis matrix and then defining the patch as 
either: 


1. a set of 16 control points 
2. a set of four comer points with associated tangent and twist vectors 


3. four boundary curves 


The basis matrix determines how the control points will be used to render the patch. Complex sur- 
faces can be created by connecting patches. 


The patch functions discussed in this section are: 


# PICpatch_geometry3d(xgeom,ygeom,zgeom) 
a PICpatch_precision(nu,nv) 
g PICput_basis(basis,index) 


# PICselect_patch_basis(uindex,vindex) 


Generating Patches 


PIClib offers basis matrices for four predefined classes of patches; Bezier Patches, Hermite 
Patches, B-Spline Patches and Sixteen-Point Form Patches. Each of the predefined classes of 
patches is described below. 


To define basis matrices for other classes of patches, use the PICput_basis() function discussed 
later in this section. Patches can be generated as a: 


@ cloud of points 
@ line mesh 


@ shaded polygon mesh 
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g@ texture mapped shaded patch 


Bezier Patches 


Bezier patches are formed from a mesh of 16 control points. The four corner points actually lie on 
the patch; the other control points are approximated. The Bezier surface has a characteristic 
polyhedron of 16 points. The matrices defining the patch are as follows: 


Xo X04 X08 X12 0 Yo Yos Yi2 ZO Z04 Z0g 212 
X01 X05 X09 X13 01 Yos Yoo Y13 Z0i 205 209 213 
Xo2 X06 X10 X14 02 Yoo Yio Y14 Z02 Z06 210 214 
X03 X07 Xi1 X15 03 Yor Yi Ys 203 207 Z11 215 


Hermite Patch 
A Hermite patch is defined by the following matrix: 


hott 
FSse 

weokemere] 
Fen e 

oto 
SaES 
Moktincne| 
SSeS 


Po 4 is the derivative of the point with respect to the parametric variable u; P” is the 
dérivative of the point with respect to w; P*™ is the derivative of the point with respect to 
u and w. 





The matrix is split into four quarters. The upper left quarter defines the four corner points; The 
lower left quarter contains the u tangent vectors at the four corner points; the upper right quarter 
contains the w tangent vectors at the four corner points; the lower right corner contains the twist 
vector. If twist is set to zero, then the patch is a Ferguson, or F-patch. This type of patch can only 
have first-order continuity with adjacent patches. An F-patch is easier to specify than a fully 
specified Hermite patch because the twist vectors can be difficult to compute. 


B-spline Patch 


A B-spline patch is defined by a characteristic polyhedron. The shape of the entire surface approxi- 
mates the polyhedron. 
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Example: 





Generate a viewport with dropped shadows. A red Bezier bicubic patch rotates around the z axis. 


a 


#include <piclib.h> 








/* define x,y and z coordinates of the control mesh: for a-bi 


PICmatrix GX = 


Picmatrix GY = 


Picmatrix GZ = 


main (arge, argv) 
int argc; 
char ** argu; 
{ 


int 
int 
int 
int 
void 





if (PICinit{)) exit (1); 
/* animate */ 


PICdouble buffer ( PIC_ON. )-> 


{ 


0.0, 


25.0, 25.0, 25.0, 25:0, 
$0.0, 50.0, 50.0, 50.0, 
75.0, 75.0, 75.0, 75.0: 


0.0, 
0.0, 
0.0, 
0.90, 


precu,precy; 


Ayiterz 
_ draw mesh:(); 


PICzbuffer( PIC_ON ); 


0.0, 0.0, 0.0, 


25..0,°50.0, 75.0, : 
25.0, 50.0, 75.0; 
25.0, 50.0, 75:0, 
2550, $0.0, -75.0 


45,0,2510,. ~30.0, 
55:0, 65.0; =20.0,: 
65.0, 25.0, -10,0; 
35.0, 75.0, 0.0 


npixl, nline; 


basis; - 
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pIcget_screen_size{ snpixl, anline ); : 
PICput_viewport ( 0, npixl-1, 0, nline-l. ee 


Piccopy_front_to_back ()7 
/* make drop shadow */ 
PICput_viewport ( 290420, 990420, 80420, 8 
Picpixel_add( -0.2, -0.2, -0.2; 0.2 )p 
PIcswap_buffer(); Wie oid it 
PICput_viewport ( 290420, 990420," 80420, 800+20. ):7 
PICpixel_add{ -0.2, -0.2,°-0.2,°-0.2 7 
Picswap_buffer () ; ; 


/* create viewport and projection */ 


Picput_viewport ( 290, 990, 80,. 800 3 
PICput_depth( 0.0, 32767.0°)3 


/* set viewing and projection parameters */ 


PiCpersp. project (45.0, 1.25; 1:0, 2048/0)70 0... 
PICLookup. view (150.0, 190.0, 150.0,.0:0, 0.0, -0.0,.. 


/* set precision in u direction, ve direction and select ‘b 


precu = 25; 
precy = 207 
basis = 0; 


PICpatch precision (precu, precy) 7 
PIcselect patch basis (basis; basis); 
PICeuclid_mode (PIC_EUCLID_ LINE) ; 





/* rotate patch around the z axis 2.5 degrees at each frame: +7 
iter = 55; 
do { 


‘PiCcolor_rgb( 1.0,°1.0, 2.09; 
PICclear rgbz ()} ne 
Picrotate_2(2. 5); 

PIGeolor rgb¢.1.0.,°0.0° 5 0.0)7 
PIcpatch_geometry 3d (GX, GY, G2):; 








draw mesh()} 












(continued on next page ) 
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PICswap_buffer(); 
. while {iter}; 
BICExit (); 


exit) 7... 


: “draw: mesh ye. 








RE OE Fe 


~ PICeolot rgb(1.0,0,0, 1.07 
“for(d 20; 4 < 4p S44) 


ee 





PICmove™ 3d:(GX{11.[01,GY [i] [0}/62 [4] [0}) + 


forty = 4p 4 < 4p 5H 
: PIcdraw_3d(GXEL} (3},GY11) (91,62.14] (37) 3 


0 ee ay 344) 





promove. 3d(6x{0} (41,GY10} (51,6200) 031)7 


: for ( LE Lap tt) . : 
PlCdvaw 3d (CX{4] £3}.,6Y (41151, 62 CF De 









PiCpatch_geometry_ 3d() 


The PICpatch_geometry_3d() function renders a 3D surface patch using the current basis matrix 
and the current patch precision. 


The shape of a 3D surface patch is defined by a set of user-specified 3D control points. The shape 
of a 3D patch is defined by a set of user-specified 3D control points. The surface patch is rendered 
using the current color and drawing mode. If polygon mode is on, the patch is shaded according to 
the current shading mode. 
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PiCpatch_ geometry _3d(xgeom,ygeom,zgeom) 
PiCmatrix xgeom,ygeom,zgeom 


xgeom,ygeom,zgeom = a set of 3D control points 





PiCpatch_precision() 


The PICpatch_precision() function specifies the number of points, lines, or polygons used to 
represent segments of a surface patch. The precision is specified for both the u and v directions and 
can be a different value for each direction. The arguments are specified as integers and must be 
greater than or equal to zero. Remember, the higher the number (nu,nv), the smoother the patch. If 
the arguments nu,nv are less than zero, the function returns a value of PIC_ERR_ARG. 


PICpatch_precision(nu,nv) 
int nu,nv; 


nunv = __ the curve’s precision in the u and v directions 


PiCput_basis() 
The PICput_basis() function defines a 4x4 basis matrix and an associated index number, which 
can subsequently be used in rendering patches. The index numbers are defined by the following 


constants: 


PIC_USER BASIS 0 
PIC_USER_BASIS 1 


PIC_USER BASIS 7 
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At initialization, the first four basis matrices contain the matrix definitions for Bezier patches, 
Hermite patches, B-spline patches and Four-point patches respectively. Unless you wish to 
overwrite these matrices, the index argument passed to PICput_basis() should range from 4 to 
PIC_MAX_BASIS. 


If index is less than zero or greater than or equal to PIC_MAX_BASIS, this function returns a value 
of PIC_ERR_ARG. 


Once defined, the basis matrix is selected by passing its associated index to the 
PICselect_patch_basis() function. 





PICput_basis(basis,index) 
PICmatrix basis; 
int index; 


basis = an matrix of 16 floating point numbers 


index = the index number associated with the basis matrix 





PiCselect_patch_basis() 


The PiCselect_patch_basis() function selects the basis matrices to be used in drawing a surface 
patch. A basis matrix is selected for both the u and v parametric directions of the patch. The basis 
matrices and their indexes must have been previously defined by PICput_basis(). If uindex or 
vindex are less than zero or > PIC_MAX_BASIS, PICselect_patch_basis() returns 
PIC_ERR_ARG. 





PICselect_patch_basis(uindex,vindex) 
int uindex,vindex; 





uindex = the index to the basis matrix for the u direction 
vindex = the index to the basis matrix for the v direction 
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The Template functions create precalculated atoms that can be quickly rendered on the screen. 
These atoms are not affected by geometric distortions, such as perspective projection or aspect ratio 
changes. sphere and user defined templates can be created and stamped on the screen. They can be 
Zbuffered, vary in size up to 256 X 256, and the user can define pixel alpha opacity percentages for 
transparency. Because templates are a raster primitive, there is little I/O overhead and transforma- 
tion pipe computation involved, therefore, you can stamp many templates at high speed. 


The Template functions are: 


ga PICatom(x,y,z,7) 

gs PICatom_light(light) 

gs PICatom_surface(surface) 

a PICget template(templ_ptr,index) 

# PICmake_ template(index,size,ix,iy,data,zdatanpixl) 
a PICmake sphere_template(index,ix,iy,z,radius) 


PiCstamp_template(index,xyz,npoint,mode) 


PIiCatom() 


The PICatom() function draws a 3D spherical atom centered at the point (x,y,z) and with radius r, 
The atom will be Phong shaded and will be lit according to the light source specified by 
PICatom_light() and surface model specified by PICatom_surface(). PICatom( is a template 
function, and, thus, will quickly render a spherical atom that is not affected by geometrical distor- 
tions. 


Atoms are a special primitive and are not handled in the same manner as the standard primitives. 
Atoms do not work correctly with perspective projection; orthographic projection should be used. 
To render atoms correctly it is recommended that the viewing volume be a cube, the viewport a 
square, and the depth range set with near = 0.0 and far = the width of the viewport. 


current viewport to a negative value, then clear the viewport to a positive z value. Also 
note that modeling transformations are applied to the center of the atom but not to the 
radius. The atom’s radius should be specified with respect to World Coordinates. Tran- 
sparent atoms have not been implemented. 


er] Atoms are not clipped in the pipeline. To clip atoms, set the z depth outside of the 
NOTE 





PICatom(x,y,z,r) 
float x,y,z,1; 
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XYZ the coordinates of the atom’s center point 


the atom’s radius 


ca 
VW 





PiCatom _lighi() 


PICatom_light() specifies a light source for a spherical atom. It has one argument, a pointer to 
PIClight_source. 





void PICatom_light(light) 
PIClight_source *light; 


light = pointer to PIClight_source 


PiCatom_surface() 


PICatom_surface() takes one argument, a pointer to PlCsurface_model. An atom’s shading is 
computed using the following equation: 


I= Ka * Li + Kd * Li * (V_normal.V_light) + Ks * Li * 
(V_eye.V_reflection) ** S exponent) 


where: 


Li = intensity of light 

Kd = diffuse coefficient of surface 

Ks = specular coefficient of surface 

Ka = ambient coefficient of surface 
S_exponent = specular exponent of surface 
V_normal = surface normal vector 

V_light = vector to light source 

V_eye = vector to the eye 

V_reflection = reflection vector 
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S_exponent is currently set to 10. 





void PICatom_surface(surface) 
PICsurface_ model *surface; 


surface = pointer to PiCsurface_model 


PiCget_template() 


PICget_template() takes a pointer to a PICtemplate structure and stores the template associated 
with index in the location pointed to by templ_ptr. The PlCtemplate structure is defined as fol- 
lows: 


typedef struct 
{ 


short type; /* sphere (type=0) or user defined (type=1) */ 

int ix; /* template positicn in vram in x */ 

int ly; /* template position in vram in y */ 

int size; /* size of template in pixels in x and y dimensions */ 
float radius; /* size of radius (spheres only) * / 
}PICtemplate; 


PICget_template() returns PIC_TRUE on success and PIC_FALSE on failure. 





int *PICget_template(templ_ptr,index) 
int index 
PICtemplate *templ_ptr 
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templ ptr = _ pointer to PlCtemplate structure 


index = template to be stored 





PiCmake_template() 


PICmake_template() takes index and size, broadcasts a user defined template consisting of npixl 
bitmapped RGBA values and their associated z depth information into off screen memory and asso- 
ciates that template with index. index is an integer that ranges from 0 to PIC_MAX_STAMP. The 
template’s position is (ix, iy). The template has a height and width of variable size; size is the same 
in the x and y dimensions. The maximum size of a template is PIC_MAX_UDTEMPLATE. 


The alpha value for each pixel in the template determines the opacity of the pixel. Alpha values 
range from 0 to 255, where 0 is completely transparent and 255 is completely opaque. 





void PiCmake_template(index,size,ix,iy,data,zdatanpixl) 
int index,ix,iy,size,npixl 

PICrgba pixel *data 

float *zdata 


index = __ template to be broadcast 
size = height and width of template 
ix,iy = position of the template 
data = bitmapped RGBA values 
npixl = number of RGBA values 
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PiCmake_sphere_template() 


PICmake_sphere_template() takes an index, radius and z-depth, renders a sphere template into 
offscreen memory and associates that template with index. index is an integer that ranges from 0 to 
PIC_MAX_STAMP. The template’s position is (ix, ty). The maximum size of a sphere template is 
PIC | MAX_ STEMPLATE, and the maximum radius is PIC_MAX_STEMPLATE/2 . In order for 
sphere templates to be stamped correctly, zbuffering must be enabled. 


void PICmake_sphere_template(index,ix,iy,z,radius) 
int index,ix,iy radius 


float z 

index = sphere template to be rendered 
ix,iy = template’s position 

Z =  2z-depth of the template 
radius = _ radius of the template 


PiCstamp_template() 


PICstamp_template() takes a template index, a point array, a point count, and a mode and stamps 
the template associated with index at the locations specified by xyz. The variable xyz consists of 
npoint (x,y,z) locations. No more than PIC_MAX_STAMP points can be stamped in one call to 
PICstamp_template(). If the template is a user defined template and mode = PIC_ON, then alpha 
opacity percentages are generated for each pixel. If mode = PIC_OFF, then the alpha values are 
ignored. Alpha values are ignored for sphere templates. Templates can be zbuffered or non- 
zbuffered. The maximum size of a non-zbuffered template is PIC_MAX_ UDTEMPLATE X 
PIC_MAX_UDTEMPLATE. The maximum size of a zbuffered template i is 

PIC_MAX_ _UDTEMPLATE/2 X PIC_MAX_UDTEMPLATE/2 . 


void PICstamp_template(index,xyz,npoint,mode) 
int index,npoint,mode 
float *xyz 
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index = template to be stamped 
xyz = locations at which template is stamped 
npoint = number of x, y, z locations 


mode = PIC_ON - alpha opacity percentages are generated 
=  PIC_OFF ~ alpha values are ignored 
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PIClib supports two types of fonts, raster fonts and vector fonts. Vector fonts supported by 
PIClib are the standard hershey vector fonts and reside in $HYPER_PATH/fonts. Vector fonts are 
composed of a series of connected 3D lines, and are affected by the current line mode and the 
current projection and modeling matrices. Vector fonts are clipped by the viewing pyramid. 


Raster fonts are a series of bit patterns displayed on the screen. Raster fonts are not affected by the 
projection or the modeling matrices, however they are clipped by the viewport. In regular rgb mode 
the current color is used to display the raster fonts. When the alpha channel is enabled, raster fonts 
are drawn in the alpha channel using the current alpha color. A set of raster font files reside in 
/usr/lib/fonts/fixedwidthfonts. You may also create your own raster fonts with the fontedit program 
supplied by Sun. 


The Fonts and Characters functions allow you to select a font type and write text using the font 
you selected. This section discusses the following functions: 


w PICopen_raster_font(font) mw PICopen_vector_font(font) 

m PICput_raster_font(font) g PICput_vector_font(font) 

m PICraster_text(ix,iy,string) s PICvector_text(string) 

w PICraster_font_text(font,ix,iy,string) m PiCvector_ font_text(font,string) 


PiCopen _raster_font() 
The PICopen_raster_font() selects (opens) the specified raster font and returns a pointer to the 
raster font structure, PICraster_font. If the font cannot be opened, a null pointer is returned. 
The following raster fonts are currently available: 

m@ aplr.10 

B cmr.b.8, cmr.b.14, cmr.r.8, cmr.r.14 


m cour.b.10, cour.b.12, cour.b.14, cour.b.16, cour.b.18, cour.b.24, cour.r.10, cour.r.12 cour.r.14, 
cour.r.16, cour.r.18, cour.r.24 


gacha.b.8, gacha.r.7, gacha.r.8 
gallant.r.10, gallant.r.19 


sail.r.6 


screen.b.12, screen.b.11, screen.r.7, screen.r.12, screen.r.13, screen.r.14 
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@ serif.r.10, serif.r.11, serif.r.12, serif.r.14, serif.r.16 


The fonts listed above are the standard fonts available with Sun’s system software. You can gen- 
erate new fonts by using the fontedit routine supplied by suntools. 


PICopen_raster_font(font) 
char *font; 





Example: 
In the following example, the serif.r.10 font is selected: 


fontl = PICopen_raster_font ("/usr/lib/fonts/fixedwidthfonts/serif.r. 10"); 


PiCput_raster_font() 


The PICput_raster_font() function sets the current raster font to a previously opened raster font 
font. The current raster font is used by the PICraster_text() function. 





PICput_raster_font(font) 
PICraster_font *font; 





PiCraster_text() 


The PICraster_text() function writes a text String, string, using the current raster font. The upper 
left corner of the text is located at point (ix,iy) with respect to the current viewport 


Raster text is clipped by the viewport, but is not affected by the projection or modeling transforma- 
tions. If alpha channel rendering is enabled, the raster text will be displayed in the alpha channel 
using the current alpha color. PiICraster_text() returns the x position of the end of the string. 





PICraster_text(ix,iy,string) 
int ix, iy; 
char “string; 
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Example: 
In the following example, the string "hello" is written at location 100,100. 


PiCraster text(100, 100, "hello"); 


PiCraster font _text() 


The PICraster_ font_text() function writes a text string, string, using the specified raster font font. 
The raster font must have been previously opened by PICopen_raster_font(). The upper left 
corner of the text is located at point (ix,iy) with respect to the current viewport 


Raster text is clipped by the viewport, but is not affected by the projection or modeling transforma- 
tions. If alpha channel rendering is enabled, the raster text will be displayed in the alpha channel 
using the current alpha color. PICraster_font_text() returns the x position of the end of the string. 


PiCraster_font_text(font,ix,iy,string) 
PiCraster_ font *font; 

int ix, iy; 

char *string; 


Examples: 


In the following example, the specified string "hello" will be output using serif.r.10 at location 
100,100. Note that in a previous example, the serif.r.10 font was opened and stored in the 
PiCraster_font structure named font1. 


PICraster font _text(fontl, 100, 100, “hello"); 
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The following program illustrates the use of raster fonts for displaying text. 





PiCopen_vector font() 


The PICopen_vector_font() selects (opens) the specified vector font and returns a pointer to the 
vector font structure, PICvector font. If the font cannot be opened, a null pointer is returned. 
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The following vector fonts are currently available: 
w@ greek] 

italicl, italic2 

lombardic 

romanl, roman2 

scriptl, script2 

speciall 

standard] 


texture 


The font types that end with a ‘‘2’’ indicate boldface versions of those fonts. 


PICopen_vector_font(font) 
char *font; 


Example: 
In the following example, the italic font is selected: 


fontl = PICopen_vector font ("italicl"); 


PiCput_vector_font() 


The PICput_vector_fontQ function sets the current vector font to a previously opened vector font 
font. The current vector font is used by the PICvector_text() function. 


PICput_vector_font(font) 
PiCvector_font *font; 
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PiCvector_text() 


The PICvector_text() function writes a text string, string, using the current vector font, Because 
vector fonts are a series of 3D lines, the text being displayed is transformed by the current transfor- 
mation matrix and affected by the current color and line mode. The text starts at location 
(0.0,0.0,0.0) and the x position of the end of the string is returned. 


PICvector_text(string) 
char *string; 


Example: 
In the following example, the string "hello" is written. 


PICvector text ("hello") ; 


PiCvector_font_text() 


The PICvector_text() function writes a text string, string, using the specified vector font font. The 
vector font must have been previously opened by PICopen_vector_font(). Because vector fonts 
are a series of 3D lines, the text being displayed is transformed by the current transformation matrix 
and affected by the current color and line mode. The text starts at location (0.0,0.0,0.0) and the x 
position of the end of the string is returned. 





PICvector_font_text(font,string) 
PICvector_font *font; 
char “string; 





Example: 


In the following example, the specified string "hello" will be output using italic1. Note that in a 
previous example, the italicl font was opened and stored in the PICvector_font structure named 
font1. 


PICvector_font_text (fontl, “"hello"); 
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The list below describes the three major types of transformations; Modeling, Viewing and Pro- 
jection. 


m Modeling transformations manipulate the object coordinate system with respect to the World 
Coordinate System. Objects are first defined in their own space, the object coordinate system, 
and then placed in the World Coordinate System by applying the modeling transformations 
(rotate, translate, and scale). The Object Coordinate System may be the same as the World 
Coordinate System, thus eliminating the transformation from object to World Space. The 
World Coordinate System is a right-hand system with y to the right, z up, and x out of 
the page (see Figure 3-2). 


m Viewing transformations transform World Space to Eye Space. The Eye Coordinate Sys- 
tem is a right-hand system with x to the right, y up, and z out of the page. The eye is at the 
origin and the viewing direction is down the negative z axis (see Figure 3-3). 


a Projection transformations map eye space into the Screen Coordinate System. The origin of 
the Screen Coordinate System is in the lower left corner with x to the right and y up (see 
Figure 3-4). 


Primitives that are not transformed by the current transformation matrix, such as raster operations, 
cursors and viewports, are specified in the Pixel Coordinate System. The origin of the Pixel Coor- 
dinate System is in the upper left corner with x to the right and y down (see Figure 3-5). 


Transformation Matrices 


There are two matrix stacks and two current matrices, which can be operated on separately. One 
stack contains the Modeling and Viewing transformations, the other holds the Projection transforma- 
tions. Objects are transformed by the product of the two current matrices: Modeling and Viewing 
(MV) matrix and Projection (P) matrix. Viewing commands replace the current MV matrix with the 
specified viewing matrix. Modeling functions cause the current MV matrix to be premultiplied by 
the matrix representing the specified transformation. For this reason, transformations should be 
specified in the reverse order in which they will be applied. Typically, transformations are specified 
in the following order: 


1. Projection transformations 
2. Viewing transformations 
3. Modeling transformations 


Object vertices and light positions are transformed by the current set of transformation matrices. 
Push and pop functions can be used to localize operations by saving and restoring transformations. 
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Figure 3-2: World Coordinate System 


x (OUT OF PAGE) 
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Figure 3-3: Eye Coordinate System 





Az (EYE AT 0, 0, 0; LOOKING 0, 0, -z) 
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Figure 3-4: Screen Coordinate System 
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Figure 3-5: Pixel Coordinate System 
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The Modeling Transformations rotate, translate, and scale objects relative to the World Coordi- 
nate System. Modeling functions cause the current MV matrix to be premultiplied by the matrix 
representing the specified function. Because of this, modeling transformations are applied to all 
objects drawn after the modeling transformation is requested. The current Modeling and Viewing 
matrix can be saved with the PICpush_transform() function and restored with the 


PICpop_transform() function. 


This section describes the following modeling transformation functions: 


Rotation Functions 

w PICrotate_x(x) 

@ PICrotate_y(y) 

# PiCrotate_z(z) 

a PiCrotate_vector(x,y,z,nx,ny,nz,angle) 


m PICput_rotate_dx(dx) 


Translation Functions 

a PICtranslate_x(x) 
 PICtranslate_y(y) 

mw PICtranslate_z(z) 

a PICtranslate(x,y,z) 
 PICput_translate_dx(tx) 


Scaling Functions 

# PICscale_x(x) 

# PICscale_y(ly) 

w PICscale_z(z) 

@ PICscale(x,y,z) 

m@ PICput_scale_dx(sx) 
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gw PICput_rotate_dy(dy) 
a PICput rotate _dz(dz) 
mw PICrotate_dx() 
a PICrotate_dyQ 
a PICrotate_dz() 


w PICput_translate_dy(ty) 
@ PICput_translate_dz(tz) 
w PICtranslate_dx() 
w PICtranslate_dy() 
w PICtranslate_dz() 


a PICput_scale_dy(sy) 
= PICput scale dz(sz) 
a PICscale_dx() 
 PICscale_dy() 
a PICscale_dz() 
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All modeling commands operate with respect to the World Coordinate System. 





Rotation 


Objects may be rotated with respect to x or y or z or an arbitrary axis. All rotations follow the 
right-hand rule. Positive rotations are counterclockwise when looking from the positive axis toward 
the origin (see Figure 3-6). 


Rotations may be absolute or incremental. Absolute rotations rotate about the x or y or z axis by 6x, 
@y, and 6z degrees. Also, arbitrary axis rotations allow you to specify an axis of rotation with a 
point, x,y,z and a direction, nx,ny,nz. This produces a rotation of © degrees about the specified axis 
with the center of rotation at x,y,z. 


Incremental rotations rotate about the x,y, or z axis by a prespecified Ax, Ay, and Az degrees. 


Positive degrees cause counterclockwise rotation; negative degrees cause clockwise 
rotation. 





The rotation functions are: 


w PICrotate_x(x) m PICput_rotate_dy(dy) 
# PICrotate_y(y) mw PICput_rotate_dz(dz) 
w PICrotate_z(z) w PICrotate_dx() 
# PICrotate_vector(x,y,z,nx,ny,nz,angle) w PICrotate_dy(Q) 
@ PICput_rotate_dx(dx) w PICrotate_dz() 
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Figure 3-6: Right-Hand Rule Rotation 
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PiCrotate Functions 


The PiCrotate functions (PICrotate_x(), PICrotate_y() and PICrotate_z()) rotate objects by a 


specified angle about the x or y or z axis. The angle is specified in degrees according to the right- 
hand rule. 


PICrotate_x(x) 
float x; 
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x = the angle of rotation about the x axis 
PICrotate_y(y) 

float y; 

y = the angle of rotation about the y axis 
PICrotate_z(z) 

float z; 

z = the angle of rotation about the z axis 


PiCrotate_vector() 


The PICrotate_vector() function rotates objects by a specified angle about an arbitrary axis. The 
axis of rotation is defined by a point and a direction as shown below: 
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Figure 3-7: Arbitrary Axis Rotation (PiCrotate_vector(10.0,0.0,0.0,0.0,-1 -0,0.0,90.0); 
Zz 







(10.0, 0.0, 0.0) UNROTATED SPHERE (0.0, 0.0, 0.0) 







(0.0, -1.0,0.0) 4 





Y | 
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x . | 


bw - 10.0) 





-Z 
PICrotate_vector(x,y,z,nx,ny,nz,angle) 
float x,y,z,nx,ny,nz,angle; 
XY ZMxnNynzZ = the point (x,y,z) and direction (nx,ny,nz) that define the axis about 


which the object will rotate 


angle 


the angle of the rotation expressed in degrees 
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Example: 


The following example demonstrates how to specify a rotation of 90° about the vector defined by 
the point [10.0, 0.0, 0.0] and the direction [0.0, 1.0, 1.0]. 


rotation: */: 


4.0, 1.0, 90.0)> 


sphere at the origin */ 





PiCput_rotate_d Functions 


The PICput_rotate_d functions (PICput_rotate_dx(), PICput_rotate_dy() and 
PICput_rotate_dz()) define a constant that specifies increments of rotation in A degrees. Objects 
can then be rotated in increments about a World Space axis (x, y, or z) using the PICrotate_d 
functions. 


PICput_rotate_dx(dx) 
float dx; 


dx = _ the incremental angle of rotation, in degrees, about the x axis 


PICput_rotate_dy(dy) 
float dy; 
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dy = __ the incremental angle of rotation, in degrees, about the y axis 
PICput_rotate_dz(dz) 

float dz; 

dz = the incremental angle of rotation, in degrees, about the z axis 


PiCrotate_d Functions 


The PICrotate_d functions (PICrotate_dx(), PICrotate_dy() and PICrotate_dz()) rotate objects 
about the x, y, and/or z axis by a predefined, incremental rotation. Before using any of the 


PICrotate_d functions, be sure to specify the incremental angle with one of the PICput_rotate d 
functions. 


PICrotate_dxQ) 
PiCrotate dy(0) 
PICrotate_dz() 


Translation 


Objects may be translated independently in x or y or z or in xyz There are two types of translations: 
absolute and incremental. Absolute translations are applied along x or y or z. Incremental transla- 
tions are applied along the x or y or z axis by a specified Ax, Ay and Az. 


The translation functions are: 


m PICtranslate_x(x)  PICput_translate_dy(ty) 
m PICtranslate_y(y) # PICput_translate_dz(tz) 
a PICtranslate_z(z)  PICtranslate_dx() 

@ PICtranslate(x,y,z) mw PICtranslate_dy() 

w@ PICput_translate_dx(tx) # PICtranslate_dz() 
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PiCtranslate Functions 


The PICtranslate functions (PICtranslate(), PICtranslate_x(), PICtranslate_y(Q) and 
PICtranslate_z()) apply a translation along x or y or z to the current transformation matrix. 


PiCtranslate(x,y,z) 

float x,y,z; 

xyz = thex, y, z translation 
PICtranslate_x(x) 

float x; 

x = _ the x translation 
PICtranslate_y(y) 

float y; 

y = the y translation 
PiCtranslate_z(z) 

float z; 

Zz = the z translation 


PiCput_translate_d Functions 


The PICput_translate_d functions (PICput_translate_dx(), PICput_translate_dy() and 
PICput_translate_dz()) specify the delta translation along each axis. Objects can then be 
translated in increments along a World Space axis (x,y, or z) using the PICtranslate_d functions. 


PICput_translate_dx(tx) 
float tx; 


x = the incremental translation in x 


PiCput_translate_dy(ty) 
float ty; 
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ty = the incremental translation in y 
PICput_translate_dz(tz) 

float tz; 

tz = the incremental translation in z 





PiCtranslate_d Functions 


The PICtranslate_d functions (PICtranslate_dx(), PICtranslate_dy() and PICtranslate_dz()) 
translate the objects along the x or y or z axis by a predefined, incremental translation. Before 
using any of the PICtranslate_d functions, be sure to specify the incremental angle with one of the 
PICput_translate_d functions. 





PICtranslate_dx() 
PICtranslate_dy() 
PICtranslate_dz() 





Scaling 
Objects may be scaled independently about x or y or Z or about xyz, simultaneously. Scale com- 
mands can shrink (sx < 1), expand (sx > 1), and mirror (sx < 0) objects. 


There are two types of scaling transformations: absolute and incremental. Absolute scaling is 
applied about x or y or z. Incremental scaling is applied about the x or y or z axis by a specified 
Ax, Ay, and Az. 


The scaling functions are: 


@ PICscale_x(x) = PICput_scale_dy(sy) 
# PICscale_ yy) # PICput_scale_dz(sz) 
w PICscale_z(z) m PICscale_dx() 
w PICscale(x,y,z) m PICscale_dy() 
@ PICput_scale_dx(sx) a PICscale_dz() 
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PlCscale Functions 


The PICscale functions (PICscale(), PICscale_x(), PICscale_y() and PICscale_z()) reduce, 
enlarge, and mirror objects by scaling the object’s x or y or z coordinates by the scaling factors x, 
y, and z, respectively. Objects can be scaled about one axis only or about all three axes. 


Positive scaling factors larger than one expand the object; less then one, reduce the 
object. Negative scaling factors mirror the scaled object across an axis. 





PICscale(x,y,z) 
float x,y,z; 


XYZ = the x, y, and z scaling factors 


PICscale_x(x) 
float x; 


x = the x scaling factor 


PICscale_y(y) 
float y; 


y = the y scaling factor 


PICscale_z(z) 
float z; 


Zz = the z scaling factor 


PiCput_scale_ d Functions 


The PICput_scale_d functions (PICput_scale_dx(), PICput_scale_dy(Q and 
PICput_scale_dz()) specify the delta scaling factor about each axis. Objects can then be scaled 
about a World Space axis (x, y or z) using the PICscale_d functions. 





PICput_scale_dx(sx) 
float sx; 
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sx = the incremental scaling factor in x 
PICput_scale_dy(sy) 

float sy; 

sy = __ the incremental scaling factor in y 
PICput_scale_dz(sz) 

float sz; 

sz = the incremental scaling factor in z 





PiCscale d Functions 


The PICscale_d functions (PICscale_dx(), PICscale_dy() and PICscale_dz()) scale the objects 
in x or y or z by a predefined scale factor. Before using any of the PICscale_d functions, be sure 
to specify the incremental angle with one of the PICput_scale_d functions. 





PICscale_dx() 
PICscale_dy(Q) 
PICscale_dz() 
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Example: 


The following code fragment illustrates the use of the incremental scaling and rotation functions. 


r 





















PICput_scale dx(3.0)7" 


/* set the. incremental: 
PICput” rotate. dz (20.0) ;. 


7* set the inerement 
for ($= 0; 1-< MAX ITERATION: 


PICcolor_rob{. BLACK )'; 
picclear_rabz().". 


PIcrotate_dz(poc 
PiCscale dx Q:p 20! 






PICcolor_ rgb{ WHI SES 
_PICpatch_geomet ry .30 (GX, GY, GA)" 


PICswap_buffer {}.7 
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Viewing Transformations map World Space into Eye Space, given the user’s view specified by 
an eye position and a view direction in the World Coordinate System. PIClib provides four viewing 
functions for specifying the view point and viewing direction: 


m PICcamera_view(x,y,z,pan,tiltsswing) 

w@ PIClookat_view(vx,vy,vz,px,py,pz,twist) 

g@ PIClookup_view(vx,vy,vz,px,py,pz,twist) 

@ PICpolar_view(dist,azim,inc,twist) 

The viewing transformations are kept on the transformation stack and are pre-multiplied by the 


modeling transformations. Therefore, the viewing transformations must be specified before any 
modeling transformations are applied. ig 


PICcamera_view(), PIClookat_view(), PIClookup_view() and PICpolar_view/() all replace 
the current transformation with the specified viewing matrix. In order to preserve the current 
modeling and viewing transformation, use the PICpush_transform() command. 


All rotations discussed in this section follow the right-hand rule, unless otherwise noted. 
All rotations are specified in degrees. 





PiCcamera_view() 


PICcamera_view() defines a viewing transformation in terms of pan, tilt, and swing angles. The 
arguments to this function define a viewpoint (x,y,z) and specify a view direction by applying a pan 
degree rotation about the y axis of the Camera Coordinate System, a tilt degree rotation about the x 
axis of the Camera Coordinate System, and a swing degree rotation about the z axis of the Camera 
Coordinate System. 


In its initial orientation, the x, y, z axes of the Camera Coordinate System are parallel to the -x, z, 
-y axes of the World Coordinate System. The eye is positioned at the origin of the Camera Coordi- 
nate System (defined by x, y, z) and the viewing vector is the positive z axis of the Camera Coordi- 
nate System. The orientation of the view vector is determined by the pan, tilt and swing parame- 
ters. See Figures 3-8 and 3-9. Note that the view vector in Figure 3-9 points toward the origin, 
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The Camera Coordinate System is a left-hand system and all rotations in it are left-hand 
rotations. 





PICcamera_view(x,y,z,pan,tilt,swing) 
float x,y,z,pan,tilt,swing; 


XYZ = 


pan = 


tilt 


swing 


the x, y, and z coordinates of the viewpoint 


the left-hand rule rotation about the y axis of the Camera Coordinate 
System 


the left-hand rule rotation about the x axis of the Camera Coordinate 
System 


the left-hand rule rotation about the z axis of the Camera Coordinate 
System 
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Figure 3-8: PiCcamera_view(100.0, 100.0, 0.0, 0.0, 0.0, 0.0) 









WORLD COORDINATE 
SYSTEM 


CAMERA COORDINATE 
SYSTEM 


VIEW VECTOR 
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Figure 3-9: PICcamera_view(100.0, 100.0, 0.0, 45.0, 0.0, 0.0) 







WORLD COORDINATE 
SYSTEM 


CAMERA COORDINATE 
SYSTEM 


VIEW VECTOR 





PiClookat_view() 


PIClookat_view() defines a viewpoint and a reference (lookat) point in World Coordinates. The 
viewpoint is at (vx, vy, vz) and the reference point is (px, py, pz). These two points define the 
view direction or view vector. The twist angle specifies a rotation about the view vector (directed 
from the viewpoint to the reference point). The view vector defines the -z axis of the Eye Coordi- 
nate System. 


PIClookat_view(vx,vy,vz,px,py,pz,twist) 
float vx,vy,vz,px,py,pz,twist; 
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vx,vy,vZ = the coordinates of the viewpoint 

px,py,pz = the coordinates of the reference (af) point 

twist = the rotation about the view vector (the -z axis of the Eye Coordinate 
System) 


PilClookup view() 


The PIClookup_view() function specifies the viewpoint and view direction with a from point and 
an at point in the World Coordinate System. These two points define the view direction or view 
vector, The twist angle specifies a rotation about the view vector (directed from the viewpoint to the 
reference point), The PIClookup_view() transformation ensures that the +y (up) vector of Eye 
Space and the +z (up) vector of World Space form an acute angle. If the view direction is (0,0+2), 
then the PIClookat_view() function is used. 


PIClookup_view(vx,vy,vz,px,py,pz,twist) 
float vx,vy,vz,px,py,pz,twist; 


vx,vy,vZ = the coordinates of the viewpoint 
PX,Py,pZ = the coordinates of the reference (at) point 
twist = the rotation about the view vector, (the -z axis of the Eye Coordinate 


System) 





PiCpolar_view() 


The PICpolar_view() function defines the viewpoint and direction in Polar Coordinates. The dist 
parameter is the distance from the view point to the origin of the World Coordinate System. The 
azim parameter is the azimuthal angle in the xy plane, measured from the y axis. The inc parameter 
is the incidence angle in the yz plane measured from the z axis. The twist parameter specifies a 
rotation about the view vector. The view vector is directed from the viewpoint to the origin of the 
World Coordinate System, and defines the -z axis of the Eye Coordinate System. 


PICpolar_view(dist,azim,inc,twist) 
float dist,azim,inc,twist; 
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dist = the distance from the viewpoint to the origin of the World Coordinate 
System 

azim = the azimuthal angle of the viewpoint in the xy plane measured from 
the y axis 

inc = the incidence angle of the viewpoint in the yz plane measured from 
the z axis 

twist = the rotation about the view vector, (the -z axis of the Eye Coordinate 


System) 
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The PIClib Projection Transformation functions define the viewing volume and type of projec- 
tion. The projection transformation maps Eye Space to Screen Space. PIClib provides four types of 
projections: 


@ Perspective pyramid 
g@ Perspective window 
m 2D orthographic projection 
mw 3D orthographic projection 


The projection functions described in this section are: 


m PICpersp_project(fovy,aspect,near,far) 

B PICwindow _project(left,right,bottom,top,near,far) 
ms PICortho _project(left,right,bottom,top,near,far) 

# PlCortho_2D_project(leftright,bottom,top,near,far) 


PiCpersp_project() 


PICpersp_project() defines a 3D perspective viewing pyramid by specifying the field-of-view 
angle, fovy, in the y direction, the aspect ratio of the x and y Eye Space dimensions, and near and 
far clipping planes. The z clipping planes are specified by distances from the eye along the -z axis 
of the Eye Coordinate System. The fovy parameter and the near clipping plane establish the size of 
the projection frustum in the y direction. The size of the projection frustum in the x direction is 
multiplied by the aspect ratio. This ratio must match the aspect ratio of the current viewport in 
order to display data without distortions. 





PICpersp_project(fovy,aspect,near,far) 
float fovy,aspect,near,far; 


fovy = the field-of-view angle in the y direction of the Eye Coordinate System 
aspect = the ratio of the x and y dimensions of the Eye Coordinate System 
near,far = the distances form the origin to the near and far clipping planes along the 


view vector (the -z axis of the Eye Coordinate System) 
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PiCwindow _project() 


The PICwindow _project() function defines a 3D perspective projection by specifying a rectangu- 
lar frustum between the near and far clipping planes. The parameters left, right, bottom and top 
define the position and size of the viewing window in the near clipping plane. These are specified 
in the x and y dimensions of the Eye Coordinate System. The parameters near and far define the 
distances from the eye to the clipping planes in the -z direction of the Eye Coordinate System. 





PICwindow project(left,right,bottom,top,near,far) 
float left,right,bottom,top near,far; 


leftright,bottom,top = the position and size of the viewing window in the near clipping 
plane, defined in the x and y dimensions of the Eye Coordinate Sys- 
tem 

near,far = the distances from the eye to the near and far clipping planes in the 


-z direction of the Eye Coordinate System 





PiCortho_project() 


The PICortho_project() function defines a 3D orthographic projection with left, right, bottom, and 
top clipping planes in the x and y directions of the Eye Coordinate System. The near and far 
parameters represent the distances from the eye to the clipping planes in the -z direction of the Eye 
Coordinate System. 


PICortho_project(left,right,bottom,top,near,far) 
float left,right,bottom,top near,far; 


leftright,bottom,top = the clipping plane specified along the x and y axes of the Eye Coor- 
dinate System 


near,far = _ the distances from the eye to the clipping planes in the -z direction of 
the Eye Coordinate System. Example: a near of -10.0 is actually 
behind the eye, and a far of 1000.0 is 1000 units in from of the eye 
at -1000.0 z. 
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PiCortho 2D _project() 


The PICortho_2D_project() function defines a 2D orthographic projection by specifying the left, 
right, bottom and top clipping planes in the xy plane of the Eye Coordinate System. 





PICortho_2D_project(left,right,bottom,top) 
float left,right,bottom,top; 


leftrightbottom,top = the left, right, bottom and top clipping planes specified along the x 
and y axes of the Eye Coordinate System 
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The Transformation Control functions manipulate the transformation matrix stacks by pushing 
and popping matrices, pre and postmultiplying matrices, and loading or retrieving matrices. There 
are two transformation matrix stacks. One stack contains the modeling and viewing transformations, 
the other holds the projection transformations. Transformation Control operations are categorized 
by the stack they are manipulating. 


Both the modeling and viewing transformation matrix and the projection transformation matrix are 
applied as follows: 


[ 0 fa Coz Cos [ 
0 Gi G12 C3} . hyytolay? 
WY a 2 Ga C22 C23 a Sat 
30 C31 C32 


The coefficients of a vector are contained in a column. 


Modeling and Viewing Transformation Control 


The Modeling and Viewing Transformation Control functions operate on the current MV 
(Modeling and Viewing) matrix and MV stack containing the modeling and viewing transforma- 
tions. These functions are listed below: 


mi PICget inverse _transform(matrix) = PiCpush_transform() 

a PICget_normal_transform(matrix) = PICpop_transform() 

u PICget_transform(matrix) = PICput_transform(matrix) 

a PICpremultiply_transform(matrix) a PICput_identity_transform() 


m PIiCpostmultiply_transform(matrix) 


PiCget_ inverse transform() 


The PICget_inverse_transform() function returns the inverse of the current MV transformation 
matrix. 





PiCget inverse transform(matrix) 
PICmatrix matrix; 
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matrix = indicates where to store the inverse of the current MV transformation 
matrix 





PiCget_normal_transform() 


The PICget_normal_transform() function returns the normal vector transformation matrix. This 
matrix is only available if shading or backface removal is on; otherwise, the identity matrix is 
returned. The normal vector transformation matrix is the inverse transpose of the upper 3x3 subma- 
trix of the current transformation matrix, 





PICget_normal_transform(matrix) 
PICmatrix matrix; 


matrix = indicates where to store the normal transformation matrix 





PiCget_transform() 


The PiCget_transform() function returns the current 4x4 modeling and viewing transformation 
matrix. The function does not change the MV transformation stack or current transformation matrix. 





PICget_transform(matrix) 
PICmatrix matrix; 


matrix = indicates where to store the current transformation matrix 





PiCpremultiply_transform() 


The PICpremultiply_transform() function premultiplies the current MV transformation matrix by 
a specified matrix. 





PICpremultiply_transform(matrix) 
PICmatrix matrix; 
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matrix = a user-defined 4x4 matrix 


PiCpostmultiply_transform() 


The PICpostmultiply_transform() function postmultiplies the current MV transformation matrix 
by a specified matrix. 


PICpostmultiply_transform(matrix) 
PICmatrix matrix; 


matrix = a user-defined 4x4 matrix 


PiCpush_transform() 


The PICpush_transform() function places a copy of the current MV transformation matrix on top 
of the stack. (The stack is not changed if it is full.) The MV transformation stack can be 
PIC_MAX_TRANSFORNM levels deep. 


PICpush_transform() 


PiCpop transform() 


The PICpop_transform() function replaces the current transformation matrix with the transforma- 
tion matrix on top of the MV stack. If the MV Transformation stack is empty, 
PICpop_transform() has no effect. 


PICpop_transform() 
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Example: 


The following code fragment illustrates the use of the push and pop operations on the Transforma- 
tion stack. 





20,4. 255°120; 
150..0, 150.0, 250.0 







- 10,0, 10,0)7 


, 804.0, '80:0;°90.0, 1.0; 220); 









tore the original coordinate system */ 





PiCput_transform() 


The PICput_transform() function loads a specified 4x4 matrix into the current MV transformation 
matrix. This function replaces the current MV transformation matrix with the specified matrix. If 


you need to save a copy of the current transformation matrix on the stack, use 
PICpush_transform(). 





PICput_transform(matrix) 
PICmatrix matrix; 
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ene 


matrix = a user-defined 4x4 matrix 





PiCput_ identity transform() 


The PICput_identity_transform( function places an identity matrix into the current MV transfor- 
mation matrix. 





PICput_identity_transform() 





The identity matrix is of the form: 


ooor 
ooreo 
oroeo 
eK OOO 


Projection Transformation Control Functions 


The Projection Transformation Control functions operate on the current matrix and stack con- 
taining the projection transformations. 


The Projection Transformation Control functions are: 


uw PICget_inverse_project(matrix) = PICpush_project() 
a PICget_project(matrix) a PICpop_project() 
m@ PICpremultiply_project(matrix) a PICput_project(matrix) 


@ PICpostmultiply_project(matrix) 


PiCget_inverse_project() 


The PICget inverse project() function returns the inverse of the current projection transformation 
matrix. 





PiICget_inverse_project(matrix) 
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matrix = indicates where to store the inverse of the current projection matrix 





PiCget_project() 


The PICget_project() function returns the current projection transformation matrix. 





PICget_project(matrix) 
PICmatrix matrix; 


matrix = indicates where to store the current projection matrix 





PiCpremultiply_project() 


The PICpremultiply_project() function premultiplies the current projection transformation matrix 
by a specified matrix. 





PICpremultiply_project(matrix) 
PICmatrix matrix; 


matrix = a user-defined 4x4 matrix 





PiCpostmultiply_project() 


The PICpostmultiply_project() function postmultiplies the current projection transformation 
matrix by a specified matrix. 





PICpostmultiply_project(matrix) 
PICmatrix matrix; 
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matrix = a user-defined 4x4 matrix 





PiCpush_project() 


The PICpush_project() function places a copy of the current projection transformation matrix on 
top of the projection stack. (The stack is not changed if it is full.) The projection stack can be 
PIC_MAX_TRANSFORM levels deep. 





PICpush_project() 





PiCpop _project() 


The PICpop_project() function replaces the current projection transformation matrix with the 
matrix on top of the projection stack. If the projection stack is empty, this function has no effect. 





PICpop_project() 


PiCput_project() 


The PICput_project() function loads a specified 4x4 matrix into the current projection transforma- 
tion matrix, replacing the original matrix. If you need to save a copy of the current projection 
transformation matrix on the projection stack, use PICpush_project(). 


PICput_project(matrix) 
PICmatrix matrix; 


matrix = a user-defined 4x4 matrix 
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The Viewport functions let you define an active area on the screen. Viewports are defined by speci- 
fying the four limits of the viewport rectangle in the Pixel Coordinate System (see Figure 3-5). 
Depending on your Pixel Machine configuration, the screen area may be 1024x1024 or 1280x1024 
for high resolution monitors and 720x480 for NTSC monitors. 


In addition to defining viewports, these functions allow you to manipulate the viewport stack; set 
and retrieve the current viewport; set and retrieve the current depth ranges; and retrieve the current 
screen size. 


The functions discussed in this section are: 


a PICget_screen_size(ix,iy) # PICpush_viewport() 
a PICget_depth(near,far) @ PICput_depth(near,far) 
m PICget_viewport(left,right,top,bottom) m PICput_viewport(left,right,top, bottom) 


a PICpop_viewport() 


PiCget_screen_ size() 


The PICget_screen_size() function returns the dimensions of the screen in the x and y directions. 
The x dimension is stored into ix; the y dimension is stored into iy. 





PICget_screen_size(&ix,&iy) 
int ix,iy; 


ixiy = the screen’s dimensions (1024x1024 or 1280x1024 for high resolution 
monitors and 720x480 for NTSC monitors) 





PiCget_depth() 


The PICget_depth(Q) function returns the z depth Tange associated with the current viewport. The z 
depth of the near plane is written into near; the z depth of the far plane is written into far. 





PiCget_depth(&near,&far) 
float near,far; 
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near the near (hither) plane 


ih 


far the far (yon) plane 





PiCget_viewport() 


The PICget_viewport() function returns the coordinates of the current viewport. The viewport’s 
initial and final x Pixel Coordinates are written into the left and right arguments, respectively; the 
initial and final y Pixel Coordinates are written into the top and bottom arguments, respectively. 





PICget_viewport(&left,&right,&top,&bottom) 
int leftright,top,bottom; 


left,right 


= coordinates of the current viewport 
top,bottom pe 





PICpop_viewport() 


The PICpop_viewport() replaces the current viewport with the viewport that is on top of the 
viewport stack. If the viewport stack is empty, this function has no effect. The depth values associ- 
ated with each viewport are maintained on the stack with the viewport. 


PICpop_viewport() 
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PlCpush_ viewport() 


The PICpush_viewport() function copies the current viewport matrix to the top of the viewport 
stack. If the viewport stack is full, this function has no effect. The maximum number of viewports 
that can be stored is PIC_MAX_VIEWPORT. 





PICpush_viewport() 





PiCput_depth() 


The PICput_depth() function defines z range associated with the current viewport, thus establish- 
ing the z range between the near and far clipping planes. With a floating point buffer, a z range of 
0.0 to 1.0 is usually sufficient. The PICclear_z() function clears the z buffer to the current value of 


far. 
PICput_depth(near,far) 





near = _ the minimum z value 


far = the maximum z value 





PiCput_viewport() 


The PICput_viewport() function defines the coordinates of the current rectangular viewport and 
loads it into the current viewport. 


Viewports must be defined in accordance with the screen’s coordinates (i.e., 1024x1024 
NOTE; OF 1280x1024 in high resolution mode and 720x480 for NTSC mode). The left and right 


coordinates range from 0 to screen_width - 1, the top and bottom coordinates range from 
0 to screen height -1. 





PICput_viewport(left,right,top,bottom) 


PIClib User’s Guide, Version 1.2 


Viewport Functions 








left,right = initial and final x Pixel Coordinates 
top,bottom = __ initial and final y Pixel Coordinates 
Example: 


To calculate the coordinates of a viewport of size 801x801 in the screen’s center (given a model 
whose screen dimensions are 1280x1024) do the following: 


left = (1279-801/2 = 239 
right = 1279 - 239 = 1040 
top = (1023-80LD/2 = ili 
bottom = 1023-111 = 912 


The coordinates of the viewport, then, are 239, 1040, 111, 912. Therefore, 


PICput_viewport (239,1040,111, 912); 
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The Shading and Depth Cueing functions allow you to use different shading modes, depth cueing, 
different types of light sources, and different surface properties. 


This section discusses the following functions: 


a PICshade mode(mode) a PICput_surface_ model(model) 

# PICget_shade_mode() = PICdepth_cue(mode) 

m PICflip(mode) w PICdepth_cue_limits(z0,r0,g0,b0,z1,11,21,b1) 

m PICclockwise(mode) m PICput_texture(type,offset_x,offset_y,size_x,size_y) 
w PIClight_ambient(red,green,blue)  PICset_texture(index) 

w PICput_light_source(type,index,light) w PICreset_texture() 

@ PIClight_switch(index,state) g PICtexture_precision(mode) 


m PICpercent_texture(texture contribution) 


PiCshade_mode() 


The PICshade_mode() function allows you to select one of the following modes: 
m@ Flat 
m” Gouraud 
m Phong 
tm No shade 


PICshade_mode(mode) int mode; 


mode = PIC_SHADE FLAT 
PIC_SHADE_GOURAUD 
PIC_SHADE PHONG 
PIC_SHADE_OFF 


tl 


WW 


N 


Whenever you switch to PIC_SHADE_FLAT, PIC_SHADE_GOURAUD or 
PIC_SHADE_PHONG, you need to specify at least one light source (see PICput_light source()) 
and a surface model (see PICput_surface_model()). The shading mode you select remains active 
and will affect all object rendered until a new shading mode is specified. See the description of 
Phong shading at the end of this section for further information on the use of this shading mode. 
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PiCget shade _mode() 
The PICget_shade_mode() function returns a value that corresponds to one of the shade modes. 
These values are: 

gm PIC_SHADE_OFF for no shading 

ms PIC_SHADE FLAT for flat shading 

mw PIC_SHADE_GOURAUD for Gouraud shading 

mw PIC_SHADE_PHONG for Phong shading 


PICget_shade mode() 





PICTlip() 


The PICflip( function reverses all surface normals of polygons that face away from the viewer. 
The sign of the normal vectors that face away from the viewer is reversed. This causes polygons 
that face away from the viewer to be illuminated so as to appear to be facing toward the viewer. 


In order for PICflip() to operate properly, the polygons must be planar. PICflipQ must 
be disabled before PICbackface() is enabled. 





PICflip(mode) 
int mode; 
mode =  PIC_ON or PIC_OFF 
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PiCclockwise() 


The PICclockwise() function defines how a normal vector of a polygon is computed. The calcu- 
lation of the normal vector affects backface removal and normal shading. The first three vertices 


(Po: P,, P.) of a polygon are used to form two vectors. When this function is set to PIC_ON, the 
normal vector is computed as 


N = (Py ~ P,) x P| ~ Py) 

When this function is set to PIC_OFF, the normal vector is computed as 
N= (P, - P,) x Pg - Py). 

The default mode is counter-clockwise (PIC_OFF). 


The direction of the vector is defined by the right-hand rule. 
NOTE 








PICclockwise(mode) 
int mode; 


mode =  PIC_ON or PIC_OFF 


PIClight_ambient() 


The PIClight_ambient() function sets the ambient light intensity for a 3D scene or a group of 
objects. Ambient light (also called background color) is the illumination that is produced by the 
combination of light reflections from objects in a scene. You can specify an ambient light intensity 
only if shading is on (i.e., if you have selected PIC_SHADE FLAT, PIC_SHADE GOURAUD or 
PIC_SHADE PHONG mode). The default setting is black (0.0, 0.0, 0.0). 





PIClight_ambient(red,green,blue) 
float red,green,blue; 
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red,green,blue = value of ambient light intensity 





PIClight_switch() 


The PIClight_switchQ function allows you to selectively turn on or off any or all of the light 
sources you have defined for a scene. The following constants can be used to manipulate all light 
sources simultaneously: 


PIC_TYPE_ALL select all light types 
PIC_LIGHT ALL select all light sources 
PIC_BLACKOUT switch all light sources off 


PIC_SUNGLASSES _ switch all light sources on 





PIClight_switch(type,index,state) 
int type,index,state; 


type =  PIC_LIGHT_DIRECT 
PIC_LIGHT SPOT 
PIC_LIGHT_POINT 


index = a user-defined number assigned to a light source and used to control 
an array of light sources 
state = PIC_ON or PIC_OFF 





PiCput_light_source() 


The PICput_light_source() function lets you select a light source. You can choose one of three 
types: 


@ Directional— a unidirectional light source used to simulate global lighting effects. The 
intensity of the light reflected from the light source depends only on the orientation of the 
surface relative to the light source. It is independent of the relative position of the surface 
being illuminated. To calculate the diffuse light contribution (Cd) from directional light 
source, the following equation is used:t 
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Cd = Kd * Le * (Vn # VI) 


To calculate the specular light contribution (Cs) from directional light source, the following 
equation is used:+ 


Cs = Ks * Lc * (Ve © Vr)**Oe 
where, 


Kd is the coefficient of diffuse reflection (from PICput_surface_model()) 
Ks is the coefficient of specular reflection (from PICput_surface_model()) 
Vn is the normal vector at a point on the object surface 

V1 is the vector from the light source (from PICput_light_source()) 

Le is the color of the light source (from PICput_light_source()) 

Ve is the vector from the object to the eye point 

Vr is the reflection vector from the object 

Oe is the object specular exponent (from PICput_surface_model()) 


Point— an omnidirectional light source that is used to simulate localized lighting effects. 
The intensity of the light reflected from the light source depends on the orientation and rela- 
tive position of the surface being illuminated. To calculate the diffuse light contribution (Cd) 
from directional light source, the following equation is used:+ 


Cd = Kd * Lc * (Vn © V1) 


To calculate the specular light contribution (Cs) from directional light source, use the follow- 
ing equation:+ 


Cs = Ks * Lc * (Ve e Vr)**Oe 
where, 


Kd is the coefficient of diffuse reflection (from PICput_surface_model()) 
Ks is the coefficient of specular reflection (from PICput_surface_model()) 
Vn is the normal vector at a point on the object surface 

V1 is the vector from the object to the light source 

Le is the color of the light source (from PICput_light source()) 

Ve is the vector from the object to the eye point 

Vr is the reflection vector from the object 

Oe is the object specular exponent (from PICput_surface_model()) 


Spot— a unidirectional light source that is used to simulate localized lighting effects, but 
restricts the zone of illumination to a cone. As with the point light source, the calculation of 
spot light depends on the orientation and relative position of the surface being illuminated. 
The size of the cone, however, can vary as the light source concentration exponent is varied, 
To calculate the diffuse contribution (Cd) of spot light source, use the following equation: + 


Cd = Kd * Le * (Vn © V1) * (Ld © VI)**Le 


To calculate the specular contribution (Cs) of spot light source, the following equation is 
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used:} 
Cs = Ks * Lc * (Ve @ Vr)**Oe * (Ld ¢ VI)**Le 
where, 


Kd is the coefficient of diffuse reflection (from PICput_surface_model()) 
Ks is the coefficient of specular reflection (from PICput_surface_model()) 
Le is the light source color (from PICput_light_source()) 

Vn is the normal vector at a point on the object surface 

Ld is the direction of the light source 

V1 is the vector from the object to the light source 

Le is the light source concentration exponent (from PICput_light_source()) 
Ve is the vector from the object to the eye point 

Vr is the reflection vector from the object 

Oe is the object specular exponent (from PICput_surface_model()) 


+ Adapted from PHIGS+ Functional Description; Revision 2.0; July 20, 1987; Andries van Dam. 


PICput_ light_source(type,index,light) 
int type,index; 
PIClight_source *light; 


type = PIC _LIGHT DIRECT 
= PIC LIGHT SPOT 
= PIC LIGHT POINT 


index = a user-defined number assigned to a light source and used to control 
an array of light sources 


light 


a data structure defining the light’s position, direction, color, concen- 
tration exponent, and angle 


Please keep the following points in mind: 
m# You need to define a light source after you define the projection for a scene. 
m Each time you change the projection, you need to redefine the light source. 
w Once a light source is turned on, it remains on until it is turned off. 
m You can define up to 50 light sources for each light type (i.e., directional, spot, or point). 
= 


There is no default setting for PICput_light_source(). Therefore, you need to specify a light 
source, 
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PilCput_surface_model() 


The PICput_surface_model() function lets you define a data structure of surface characteristics. 





PICput_surface_model(model) 
PICsurface_model *model; 


model = a data structure defining the object’s ambient color (for red, green, 
and blue), diffuse color (for red, green, and blue), specular color (for 
red, green, and blue), specular exponent, and transparency 





PiCdepth_ cue() 


The PICdepth_cue() function allows you to turn depth cueing mode on or off. Depth cueing 
applies to points and vectors. When in depth cueing mode, points and vectors vary according to 
colors defined at the depth cueing limits. 





PIiCdepth_cue(mode) 
int mode; 


mode PIC_ON (turn depth cueing on) 


PIC_OFF (turn depth cueing off) 


Wood 





PiCdepth_ cue _limits() 


The PICdepth_cue_limits() function sets the z limits and color range of depth cueing. 





PICdepth_cue_limits( 29% 9899217781) 


float Zo" 8qg-24 18 b4i 
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Zy = the z depth at which to begin depth cueing 
TyBqbo = the color at the beginning of the depth cueing limits 
Z4 = the z depth at which to end depth cueing 

14/8474 = the color at the end of the depth cueing limits 





All points or lines that fall within the specified z depth range (29:24) will have their color calculated 
by the following equation: 


so Z-ZO0 #3, _7 
i=io+ a : (i1 — io) 





Where z, and z, are the z limits described above, i, and i represent the intensities at the z limits, 
z is the depth of the current point, and i is the computed intensity. 


These z limits and colors are active until another PICdepth_cue_limits() is defined. ZZ are not 
necessarily the same as near and far clipping planes. 


The colors are linearly interpolated based on the position of the objects relative to the z depth lim- 
its. 


PiCput_texture() 


PICput_texture() defines an area of offscreen memory to be used as a single texture. There can be 
sixty-four of these texture areas. type is the type of texture, resident or virtual. Currently, only 
resident is supported. type=null represents resident texture. offset_x, offset_y is the starting location 
of texture in off-screen video RAM. size_x, size_y is the size of texture in pixels in off-screen 
video RAM. 





PICput_texture(type, offset_x, offset_y, size_x, size_y) 
unsigned long *type; 
unsigned long offset_x, offset_y, size_x, size_y; 
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type = type of texture 
offset_x, offset_y = starting location of texture in offscreen VRAM 
size_x, size_y = size of texture in pixels in offscreen VRAM 


PiCset_texture() 


PICset_texture() sets the current area to be used for texture mapping as defined by 
PICput_texture(). 


index is the value returned by PICput_texture(), and it is used to reference the texture area defined 
by the associated PICput_texture() routine for all commands that follow and use texturing. 


PIC_DEFAULT_TEXTURE can be used as index to reference the entire 256x256 texture area. 


If the texture maps are less than 256 X 256, PIClib supports multiple texture maps. 
They can be used simultaneously. 








PICset_texture(index) 
int index; 


index = value used to reference the texture area 
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PiCreset_texture() 
PICreset_texture() sets the current area to be used for texture mapping. 
The current_texture_id and the next_texture_id are set to PIC_DEFAULT TEXTURE. 


The texture area is set to 256X256. 


void PiCreset_texture() 





PiCtexture_precision() 


PICtexture_precision() sets the precision for the display of texture mapped polygons. This is 
used in perspective mode and determines the number of times that a polygon is split when displayed 
to correct the perspective distortion of the texture. The mode argument is defined as follows: 


PIC_LOW (default) 
PIC_MEDIUM 
PIC_HIGH 


mode is the number of times that the polygon is split. 


PICtexture_precision() takes any integer as mode; we have defined PIC_LOW, PIC_MEDIUM, 
and PIC_HIGH, but you can specify whatever integer you want. 


The default setting corresponds to no splitting of polygons and causes the texture 
mapped polygons to appear as they have in previous releases. It should be noted that 
setting the mode to anything other than PIC_LOW will impact the speed of display of tex- 
ture mapped polygons. 





This function does not support the PICpoly_point macros. 


int PICtexture_precision(mode) 
int mode; 
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mode = PIC_LOW (default) 
PIC_MEDIUM 
PIC_HIGH 





PiCpercent_texture() 


The PICpercent_texture() function indicates the contribution of the texture map’s intensity value 
at each pixel with a floating point argument between 0.0 and 1.0. The compliment of this argument 
is the contribution of the interpolated Gouraud shaded value at each pixel. An argument of 0.0 indi- 
cates that the surface intensity is all Gouraud shaded. An argument of 1.0 means the surface inten- 
sity is all texture map. 





PiCpercent_texture(texture_ contribution) 
float texture_contribution 


texture_contribution = contribution of the texture map’s intensity value at each pixel. This 
value ranges from 0.0 to 1.0. 


Phong Shading 
PIClib allows you to select Phong shading as the shade mode. 
The following variables are used to describe the lighting calculations presented below: 


Ia(x) _ is the ambient light intensity for the scene (from PIClight_ambient()), 

Kd(x) is a component of the object’s diffuse reflection coefficient (from the d_* ele- 
ments of PICsurface_model()), 

Ka(x) is a component of the object’s ambient coefficient (from the a_* elements of 
PICsurface_model()). 

Ks(x) is a component of the object’s specular reflection coefficient (from the s_* ele- 
ments of PICsurface_model()). 

Vn is the normal vector at a point on the object surface. 

Vi is the vector from the light source to the point on the object’s surface (derived 
from the x,y,z or nx,nynz elements of PIClight_source()). 
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Lc(x) is a component of the color of the light source (from the r, g, b elements of 
PIClight_source()). 


Ve is the vector from the object to the eye point. 

R is the reflection vector from the object which is the mirror vector of V/ about 
Vn. 

S is the object’s specular exponent (from the exp element of 
PICsurface_model()). 

x is the red, green, and blue components of light. 

Is number of lights; 5 point light sources and 5 directional lights. 


The following formula is used to determine the shading of a pixel: 


Color (x) = Ia(x) * Ka(x) +Kd (x) * = Lei(x) * (N ¢ Lj) + Ks(x)* = Lei(x) * (BE R;)S 


The first term of the equation is the global ambient contribution to the pixel. This depends on the 
global illumination and the ambient coefficient of the object’s surface model. 


The second term is the diffuse elimination of all light sources and is controlled by the diffuse 
coefficient of the object’s surface model! (Kd) and the color and intensity of the light (Lc) and rela- 
tive orientation of each light source compared to the normal of the object at that point (N . L). 


The last term is the specular contribution of all light sources, and it is controlled by the specular 
coefficient of the object’s surface model (Ks), the color and intensity of each light (Lc?) and the dot 
product of (E. R)**S, where E is the vector in the eye direction and R is the reflection vector from 
the object which is the mirror of L about N. S is the specular coefficient in the object’s surface 
model. The higher the value of S the sharper and smaller the area of the specular highlights. 


Using Phong Shading 


Because the pixel nodes contain a fixed amount of memory allocated for program storage, PIClib 
uses a pixel node code overlay mode facility. This allows PIClib to download code into the pixel 
nodes whenever it is needed. For the most part, it is transparent, that is the user does not have to 
keep track of what is loaded into the nodes; downloading of code is an automatic process. How- 
ever, Phong shading is a special case. In order to render polygons as quickly as possible, the Phong 
shading code must be manually downloaded. This is done to avoid checking the overlay mode in 
PICpoly_point() commands, which can slow polygonal rendering considerably. 


For Phong shading to work correctly, Phong overlay mode must be downloaded, while in 
PIC_SHADE_ PHONG mode, before any surface model, light source (direct or point), ambient light 
or poly_point command is called. This is done by calling 
PICput_overlay_mode(PIC_PIXEL_PHONG). Once PICput_overlay_mode() is called, lights, 
ambient light and surfaces can be defined and Phong shaded polygons can be rendered. The data 
structures for lights and surfaces are static, so PICput_overlay_mode() need only be called when 
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surface or lights change and must be called before rendering polygons. It is important to remember 
that other PIClib calls can download code over the Phong shading code. You should check to make 
sure that Phong overlay mode is loaded. This can be done by using the PICget_overlay_mode() 
function. For example to render a Phong shaded polygon: 


PICeuclid_mode (PIC_EUCLID_POLYGON) ; 
PICshade_mode (PIC_SHADE_PHONG) ; 


mode = PICget_overlay mode(); 

if (mode != PIC_PIXEL PHONG) 
PICput_overlay_mode(PIC_PIXEL PHONG) ; 

set_surface(); 

set_lights(); 

draw_object () ; 


The functions that download code are: 
1, Overlay mode 1: everything rendered in points or lines 


2. Overlay mode 2: PICatom_surface(), PICatom_ light), PICatom(, PICpixel_addQ), 
PICpixel_multiply0, PICput_scan_line(), PICbroadcast_data() 


3. Overlay mode 3: PICmake_sphere_template(), PICmake_template(), 
PICstamp_template() 


4. Overlay mode 4: Phong shading 


To optimize program performance, it is recommended that switching between overlay modes be 
kept to a minimum. Phong shading always generates alpha mattes. 
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The Pixel Machine uses the rgb color system. All colors are specified as percentages of red, green, 
and blue. You can choose from a palette of 2“ colors. 


PIClib offers the following color functions: 
# PICcolor_rgb() 
w PICcolor_alpha() 


PiCcolor_rgb() 


The PICcolor_rgb() function defines the current color. The current color is used to color all 
objects subsequently specified by the user (i.e., points, lines, polygons, etc.). 


PICcolor_rgb(t,g,b) 
float r,g,b; 


rg,b = __ the specified percentages of red, green, and blue (between 0.0 and 1.0) 


All colors are specified as normalized floating point numbers. A default color map is loaded each 
time hypinit is executed. The specified percentages of red, green and blue are multiplied by 255 
and used as an index into a color lookup table. rgb color tables are used primarily for gamma 
correction. The lookup table does not affect the frame buffer, only the contents displayed on the 
video screen. 


PiCcolor_alpha() 


The PICcolor_alpha() function defines the current alpha color. You can choose from 256 colors. 


PICcolor_alpha(alpha) 
int alpha; 
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alpha = __ the index that selects the current alpha color (between 0 and 255) 





The current alpha color is used when writing into the alpha channel. 


ore PICenable_alpha() must be set before you can write into the alpha channel. 
NOTE 
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The Display functions perform operations on pixels, images, viewports, and data memory, such as, 
read or write a scan line of rgb pixels and enable or disable the alpha planes, overlay modes, or 
double buffer mode. 


These functions are grouped into the following categories: 


m Clear functions clear the current viewport to a specified color (rgb or alpha) and clear the z 
depth settings: 


a PiCclear_alpha() 
o PICclear_rgbQ) 
o PiCclear_zQ) 
a PiCclear_rgbz() 
m Buffer functions return data on the buffer and buffer mode and provide double buffering 
operations: 
o PiCget_buffer() 
o PiCget_buffer_mode() 
o PICdouble_buffer(mode) 
o PiCswap_buffer() 


# Overlay functions enable or disable writing to the alpha channel and select overlay mode: 
o PICalpha(mode) 
o PICdisplay_overlay(mode) 
ao PiCoverlay_mode(mode) 
o PICput_overlay_mode(mode) 


o PICget_overlay_mode(mode) 


m Scan Line functions read and write from video and floating point memory banks: 
Oo PICput_scan_line(ix,iy,red,green,blue,alphanpixl,mode) 
o PICget_scan_line(ix,iy,red,green,blue,alphanpixl,mode) 
oO PICbroadcast_data(memory,ix,iy,datanword,mode) 


o PICcomposite_mode(mode) 
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a Copy functions copy screen and/or z data between buffers: 
o PICcopy_front_to_back(Q) 
o PICcopy_back_to_ext(buffer,ix,iy) 
a PICcopy_ext_to_back(buffer,ix,iy) 
a PICcopy_z to ext() 
o PICcopy_ext_to_z() 


PiCclear_alpha() 


The PICclear_alpha() function clears the alpha planes of the current viewport to the current alpha 
color. 


PICclear_alpha() 


PiCclear_rgb() 


The PICclear_rgb() function clears the rgb planes of the current viewport to the current rgb color. 


PICclear_rgb() 





PiCclear_z() 


The PICclear_z() function clears the z depth of the current viewport to the far value specified by 
the PICput_depth(Q) function. 





PICclear_z() 
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PiCclear_rgbz() 


The PICclear_rgbz() function clears the rgb planes of the current viewport to the current rgb color 
and clears the z depth to the far value specified by the PICput_depth() function. 





PICclear_rgbz() 





PiCget_buffer() 


The PICget_buffer() function returns an integer indicating the number of the current display 
buffer. The number is either PIC_BUFFER_ZERO or PIC_BUFFER_ONE. When you initialize 
PIClib, the front buffer is PIC_BUFFER_ZERO (this buffer is displayed on the screen) and the 
back buffer is PIC_BUFFER_ONE. 





PICget_buffer0) 


PiCget_buffer_mode() 


The PICget_buffer_mode() function returns an integer indicating which buffer mode is being used 
(single or double). PIC_SINGLE BUFFER indicates single buffer mode; 
PIC_DOUBLE_BUFFER indicates double buffer mode. 





PICget_buffer_mode() 
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PiCdouble_buffer() 


The PICdouble_buffer() function enables or disables the use of double buffering. When enabled, 
objects are drawn into the back buffer, which is not displayed on the screen. (When in double 
buffering mode, use the PICswap_buffer() function after completing a frame.) When disabled, 
objects are drawn into the front buffer only, which is displayed on the screen. 


PICdouble_buffer(mode) 
int mode; 


mode = _ PIC_ON or PIC_OFF 





PiCswap buffer() 


The PICswap_buffer() function swaps the back and front buffers. This function is called during 
animation. Objects are drawn in the back buffer and displayed in the front buffer. (The back buffer 
is not displayed.) 


Be sure to first enable double buffering (PICdouble_buffer()) before using 
PICswap_buffer(). 


PICswap_buffer() 


PiCdisplay_overlay() 


The PICdisplay_overlay() function enables or disables the display of overlays. If overlays are 
disabled (mode = PIC_OFF) the rgb channels are always displayed. If overlays are enabled 
(mode = PIC_ON) the rgb or alpha channels are conditionally displayed according to the mode set 
by PICoverlay_mode(). 





PICdisplay_overlay(mode) 
int mode; 
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mode =  PIC_ONor PIC_OFF 





PiCoverlay_mode() 


The PICoverlay_mode() function selects the overlay mode to be used when overlays are enabled. 
When overlays are disabled, the rgb signal is always displayed; when enabled, the alpha channel 
and inverted rgb can be displayed, or you can toggle between the alpha and rgb channels. When 
rendering into the alpha channel, it is suggested that you use mode PIC_OVERLAY_NON_ZERO 
and avoid the alpha entry 255. When using the cursor, the PIC_OVERLAY_HIGH_BIT mode 
should be used. 





PICoverlay_mode(mode) 
int mode; 


mode = PIC_OVERLAY_OFF Disable overlays; rgb signal always displayed 


= PIC_OVERLAY_NON ZERO If the alpha channel is non-zero, display it; otherwise, 
display the rgb signal; if the alpha channel is all 1’s (a = 
255), display inverted rgb 

= PIC_OVERLAY_HIGH_BIT Toggle mode; if the most significant bit of the alpha channel 
is set (i.e., bit 7 = 1), display the contents of the alpha chan- 
nel; if it is not set (i.e., bit 7 = 0), display the rgb signal 


Be sure to enable writing into the alpha channel before using overlays. See PICalpha(). 
Be sure to enable the display of overlays. See PICdisplay_overlay(. 
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PiCput_overlay mode() 
PICput_overlay_mode() takes an overlay mode and downloads the code associated with the over- 


lay. At present, only a mode equal to PIC_PIXEL_PHONG will download any code. The overlay 
must be loaded before any PIClib function can be called. 


void PICput_overlay_mode(mode) 
int mode 


mode = PIC PIXEL_PHONG 


PiCget_overlay mode() 


PICget_overlay_mode() returns the overlay mode that is currently loaded into the pixel nodes. 


int PICput_overlay_mode() 


PiCalpha() 


The PICalpha() function enables or disables rendering into the alpha channel. When disabled, 
rendering is done in the rgb channels. You should refer to PICdisplay_overlay() and 
PICoverlay_mode() to display contents of the alpha channel. Objects are rendered using the 
current alpha color set by PICcolor_alpha(). To load a 24 bit color into the alpha channel lookup 
table, use PICput_alpha_map_entry(). Lines are not rendered into the overlay modes, however, 
cursors, raster text, flat and filled polygons are. 


PICalpha(mode) 
int mode; 
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mode = PIC _ONor PIC_OFF 


Example: 


The following program illustrates alpha channel rendering. 
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typedef struct {oo -) 
J fToat 

», .Eboat. 

Poo caf Noa. 
}. alphasrgo; 


main{) 


f 


Picclear alpha {};: 


ye ‘clear ‘alpha anne: 


/* etiabie ‘alpha re 


Lp seleét ‘overlay ‘mode 


PI€shade_mode (PTC's 


_7* SHADE: PIAT or SHADE. 





(continued on next page ) 
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revosowosreys |e 
PIC A OVER B 
PIC B OVER A 
. 


PIC_A OUT B 
























PIC B OUT A 








PIC_A_ATOP B 
















PIC_B ATOP A 


PIC_A_XOR B 
PIC_PLUS 


The compositing operation requires two source images. One is the image in the current buffer (the 
back buffer in double buffer mode and the front buffer in single buffer mode). The other image is 
sent to the Pixel Machine via the Pipeline using the PICput_scan_line() function. The two images 
are composited using the current compositing mode, and the result is stored in the current buffer, 
overwriting the original image. 











PICcomposite_mode(mode) 
int mode; 
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ix,iy = the coordinates of the scan line. The left-most pixel of the scan line 
is positioned at Pixel Coordinates (ix,iy). (See Figure 3-5.) 

red,green,blue,alpha = arrays that determine the color of each pixel 

npixl = the number of pixels in the scan line. PICput_scan_line() can write 


an individual pixel by setting npixl to one. 


mode = PIC _RGB PIXELS 


= PIC_RGB PACKED PIXELS 


= PIC_RGBA PIXELS 


= PIC_RGBA_PACKED_PIXELS 


= PIC_ABGR_PACKED_ PIXELS 


= PIC_RGB_ ENCODED PIXELS 


=  PIC_EXTENDED_VRAM 


3-124 


Each pixel is 24 bits of rgb; 8 bits from each red, 
green, blue array. 


Each pixel is 24 bits of rgb from a packed array 
pointed to by red. The pixel components are stored 
in rgb order, and the pixels are stored in rgb order. 
The first byte in red contains the red component of 
the first pixel. Alpha remains unchanged. 


Each pixel is 32 bits of rgba; 8 bits from each red, 
green, blue, alpha array. 


Each pixel is 32 bits of rgba. from a packed array 
pointed to by red. The pixel components are stored 
in rgba. order. The first byte in red contains the red 
component of the first pixel. 


Each pixel is 32-bits of rgbo. from a packed array 
pointed to by red. The pixel components are stored 
in abgr order. The first byte in red contains the 
alpha component of the first pixel. 


Each pixel is 24 bits of rgb; 8 bits from each red, 
green blue array. The alpha array contains count 
numbers that determine how many pixels of the 
same color are to be written. A count number can 
range from 0, which means that the run is 1 pixel 
long, to 255, which means that the run is 256 pixels 
long. In this mode, npixl refers to the number of 
runs in the scan line, 

If PIC_EXTENDED_ VRAM is added to mode, the 
scan line is written into the extended video memory. 
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Display Functions 


The PICget_scan_line() function lets you read a scan line of rgb or rgbo. pixels from the screen by 
specifying the location of the first (left-most) pixel of the scan line, (ix,iy); the number of pixels in 
the scan line, npixl; and the format used to read the pixels, mode. 


and not the display buffer. {t is recommended to call PICwait_psync() before the first 


vor If the system is in double-buffer mode, the scan line will be read from the write buffer 
NOTE 


call to PICget_scan_line(). This ensures that the entire frame has been drawn before 


any scan lines are read. 


PiCget scan _line(ix,iy,red,green,blue,alpha,npixl,mode) 


int ix,iy; 

PICpixel *red, *green, *blue, *alpha; 

int npixl; 

int mode; 

ix,iy = _ the coordinates of the scan line. The left-most pixel of the scan line 
is positioned at Pixel Coordinates (ix,iy). (See Figure 3-5). 

red,green,blue,alpha = arrays to store the scan line 

npixl = the number of pixels in the scan line. PICget_scan_line() can read 
an individual pixel by setting npixl to one. 

mode = PIC_RGB PIXELS Each pixel is 24 bits of rgb (8 bits stored to each 


= PIC_RGB PACKED PIXELS 


= PIC_RGBA PIXELS 


= PIC_RGBA_PACKED PIXELS 


=  PIC_ABGR PACKED PIXELS 
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red, green, blue array). 

Each pixel is 24 bits of rgb written to an array 
pointed to by red. The pixel components are stored 
in rgb order. The first byte in red contains the red 
component of the first pixel. 


Each pixel is 32 bits rgba (8 bits stored to each red, 
green, blue, alpha array) 


Each pixel is 32 bits of rgba stored to a packed 
array pointed to by red. The pixel components are 
stored in rgba order. The first byte in red contains 
the red component of the first pixel. 


Each pixel is 32 bits of rgba written to an array 
pointed to by red. The pixel components are stored 
in abrg. order. The first byte in red contains the 
alpha component of the first pixel. 
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PIC_RGB_ENCODED PIXELS Each pixel is 24 bits of rgb; 8 bits from each red, 

- 7 green blue array. The alpha array contains count 
numbers that determine how many pixels of the 
same color were read. A count number can range 
from 0, which means that the run is 1 pixel long, to 
255, which means that the run is 256 pixels long. In 
this mode, npixl refers to the number of runs in the 
scan line. 


PIC_EXTENDED_VRAM If PIC_EXTENDED_VRAM is added to mode, the 
scan line is read from the extended video memory. 





PiCput_image_ header() 


PICput_image_header() writes the PICimage_header and the optional user header (if one exists) 
to the specified file. 


file is a file descriptor obtained from a previous call to fopen(3). The file must have been success- 
fully opened for writing and the file pointer should be pointing to the beginning of the file (i.e., no 
previous writes have been issued). Upon return from PICput_image_header(), the file pointer 
will be set to where the pixel data should start (i.e., past the image and optional headers). 


PICput_image_header() will convert the PiCimage_header structure pointed to by image_header 
into a string of decimal ASCII characters and write it to the file pointed to by file. If the magic 
structure member is 0, it will be set to PIC_IMAGE_MAGIC before being written. If magic is 


non-zero, it will be written as is. 


If optional_header is non-zero, the characters pointed to it will be written to file immediately after 
the image header. image_header->optional_header size bytes will be written. 


PICput_image_header() returns 0 upon success and -1 on failure. PICput_image_ header() will 
fail for the following reasons: 


m the magic number is not PIC_IMAGE_ MAGIC, or 


m an error was returned by the fwrite(3) system call while writing either the image header or 
the optional header. 
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No value in the PICimage_header should be greater than 1.2,000,000. 





All Pixel Machine libraries share the same image header format. 


#include <stdio.h> 
#include <picimage.h> 


int PICput_image_header(file, image_header, optional_header) 


FILE *file; 

PICimage_ header *image_ header; 

unsigned char *optional_header; 

file = file to which the header is written 

image_header = pointer to the PICimage_header structure 

optional header = pointer to characters to be written following the header 


PiCget_image_header‘() 


PICget_image_header() reads the PICimage_header and the optional header (if one exists) from » 
the specified file and returns them to the caller. 


file is a file descriptor obtained from a previous call to fopen(3). The file must have been success- 
fully opened for reading and the file pointer should be pointing to the beginning of the file (i.e., no 
previous reads have been issued). Upon return from PICget_image_header(), the file pointer will 
be set to the beginning of the pixel data (i.e., past the image and optional headers). 


PICget_image header() reads in the first PIC_IMAGE_ HEADER SIZE bytes from the file, con- 
verts them from ASCII into unsigned longs and place them into the correct locations in the structure 
pointed to by image header. Except for the magic and optional_header_size fields, none of the 
information in the header is checked for validity. 


If an optional header is present (image_header->optional_header_size is not 0), memory will be allo- 
cated (via malloc(3)) and image_header->optional_header_size bytes will be read. A pointer to the 
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allocated memory will be returned in *optional_header. If no optional header is present, 
*optional_header will be set to NULL. 


PICget_image_header() returns 0 upon success and -1 on failure. PiICget image header() will 
fail for one of the following reasons: 


m the magic number is not PIC_IMAGE MAGIC, or 
m an crror was returned by the fread(3) system call while reading either the image header or the 


optional header. 


ore All Pixel Machine libraries share the same image header format. 
NOTE 





#include <stdio.h> 
#include <picimage.h> 


int PICget_image_header(file, image header, optional header) 





FILE *file; 

PICimage header *image_ header; 

unsigned char **optional header; 

file = file from which the header is read 
image header = location into which the header is read 
optional header = additional bytes to be read 
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PiCbroadcast_data() 


The PICbroadcast_data() function broadcasts a line of data to extended video memory (memory = 
PIC_BROADCAST_VRAM) or to z memory (memory = PIC_BROADCAST ZRAM). The data 
consists of 32-bit words stored in an array data. 


If the data is broadcast to the extended video memory, each 32-bit word should be organized as four 
8-bit pixel components. These components can be stored in rgbo order or in obgr order depending 
on the parameter mode. A common use of PICbroadcast_data() is to broadcast textures to VRAM 
so that all nodes receive the same data. 


If the data is broadcast to the z memory, each 32-bit word can contain any data (floating point, long 
integer, 2 short integers or 4 bytes). The number of 32-bit words of data to be broadcast is set by 
nword. The starting x and y memory addresses are ix,iy. 





PICbroadcast_data(memory,ix,iy,datasnword) 
int memory, ix, iy; 


int *data; 
int nword; 
int mode; 
memory = PIC_BROADCAST_VRAM or 
= PIC_BROADCAST_ZRAM 
ix,iy = the starting x and y memory addresses 
data = an array of 32-bit words 
nword = the number of 32-bit words to be broadcast 
mode = PIC_RGBA_PACKED PIXELS Each pixel is 32 bits of rgbo, from a packed array 


pointed to by data. The pixel components are 
stored in rgbo order. The first byte in data contains 
the red component of the first pixel. 


= PIC_ABGR_PACKED PIXELS Each pixel is 32-bits of rgba from a packed array 
pointed to by data. The pixel components are 
stored in obgr order. The first byte in data contains 
the alpha component of the first pixel. 
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PiCcopy front_to_back() 


The PICcopy_front_to_back() function copies the contents of the current viewport from the front 
buffer to the back buffer. 


PICcopy_front_to_back(Q) 


PiCcopy_ back to front() 


PICcopy_back_to_front() copies the contents of the back buffer to the front buffer. This function 
only copies the contents of the current viewport. 


void PICcopy_back_ to front() 





PiCcopy_back to ext() 


The PICcopy_back_to_ext() function copies the contents of the current viewport from the back 
buffer to the extended screen buffer. 

The coordinates ix, iy are used with the PIC_SCREEN BUFFER constant to specify where in the 
off-screen image buffer to copy the contents of the current viewport. The size of the off-screen 
buffer varies, depending on the model, as follows: 
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Off-screen Buffer Size 


2048x2048 
2048x2048 
2048x2048 
1280x2048 
2560x1024 
1024x2048 
2048x1024 
































1280x1024 


1024x1024 | 


Because each Pixel Node processor only has access to every other Nx x Ny pixels on the screen, the 
ix,iy values have to be chosen carefully when copying to/from PIC_SCREEN BUFFER. For 
example, if the current viewport starts at a multiple of Nx x Ny pixels on the screen, then the ix,ly 
offset values would also have to be a multiple of Nx and Ny. The table below lists the Nx and Ny 
values for the various Pixel Machine models. 











There are two available extended buffers: PIC_TOP_BUFFER and PIC_BOTTOM_BUFFER. 
These are used for copying rgb planes to off-screen memory for 3D compositing and other purposes. 
When buffer is set to PIC_SCREEN BUFFER, the extended memory is treated as a single large 
buffer and you need to specify the location indicating where to place the contents of the current 
viewport. Use PIC_SCREEN_BUFFER when you want to create flipbooks or scroll through a 
large image. 





PICcopy_back_to_ext(buffer,ix,iy) 
int buffer; 
int ix, iy; 
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buffer = PIC_TOP_BUFFER, PIC_BOTTOM BUFFER, or 
PIC_SCREEN BUFFER 
ix, iy = _ coordinates in an off-screen image buffer 


PiCcopy ext to back() 


The PICcopy_ext_to_back() function copies a region from the extended-screen buffer to the 
current viewport. 


PICcopy_ext_to_back(buffer,ix,iy) 
int buffer; 
int ix, iy; 


buffer = PIC_TOP_BUFFER, PIC_BOTTOM BUFFER, or 
PIC_SCREEN BUFFER 
ix, iy = coordinates in an off-screen image buffer. These coordinates are used 


with the PIC_SCREEN BUFFER constant to specify what part of 
the off-screen image buffer to copy into the current viewport. The 
size of the off-screen buffer varies, depending on the model. See the 
description of PICcopy_back_to_ext() above for the buffer sizes. 


Since each Pixel Node processor only has access to every other Nx x Ny pixels on the screen, the 
ix,ty values have to be chosen carefully when copying to/from PIC_SCREEN BUFFER. For 
example, if the current viewport starts at a multiple of Nx x Ny pixels on the screen, then the ix,ty 
offset values would also have to be a multiple of Nx and Ny. The table in Figure 3-11 lists the Nx 
and Ny values for the various Pixel Machine models. 


There are two available extended buffers: PIC_TOP_BUFFER and PIC_BOTTOM_ BUFFER. 
These are used for copying rgb planes to off-screen memory for 3D compositing and other purposes. 
When buffer is set to PIC_SCREEN_BUFFER, the extended memory is treated as a single large 
buffer and you need to specify the location indicating what part of the off-screen image buffer to 
copy into the current viewport. Use PIC_SCREEN_BUFFER when you want to create flipbooks or 
scrolling through a large image. 
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PiCcopy z to ext() 


The PICcopy_z_ to ext() function copies the contents of the z buffer to the extended-screen z 
buffer. The region copied is defined by the current viewport. 





PICcopy_z to_ext() 





PiCcopy _ext_to 2() 


The PICcopy_ext_to_z() function copies the contents of the extended-screen z buffer to the screen 
z buffer. The region copied is defined by the current viewport. 





PICcopy_ext_to_z0) 
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The Hidden Surface Removal functions allow you to create realistic images by removing those 
surfaces that are hidden from view. These functions are: 


w PICzbuffer(mode) 
m= PICbackface(mode) 
mw PIiCzbuffer_ lines(mode) 


PiCzbuffer() 


The PICzbuffer() function enables/disables hidden surface removal. The function removes hidden 
surfaces by comparing the z depth value of each pixel ina polygon to the contents of the z buffer 
for that pixel, and writes only those pixels that have a value less than that of the z buffer. The z 
buffer is initialized by the PICclear_z() function. 


The table below describes the available z buffer modes: 


Mode 


PIC_OFF 









Description 




















neither tests against nor writes the z buffer 






tests against and writes the z buffer 






PIC_READ ONLY 
PIC_WRITE_ONLY 






tests against but does not write the z buffer 











writes the z buffer unconditionally 








PICzbuffer(mode) 
int mode; 


mode =  PIC_ON or PIC_OFF 
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PiCbackface() 


The PICbackface() function removes surfaces that face away from a specified viewing position. In 
order for backface removal to operate properly, the object must be closed and the polygons must be 
planar. 


This function uses the eye position and the normal vector to the polygon to compute visibility. If 
no normal is given (with PICpoly_normal()), one is constructed from the first 3 vertices of the 
polygon. For this reason if it important to specify your vertices in a consistent order. The default 
order for specifying the vertices of a polygon is counterclockwise, viewing the polygon from the 
outside. For more information, refer to the description of the PICclockwise() function. 


in order for backface removal to operate properly, make sure the polygons are planar. 
Also note that PICflip0 must be disabled before PICbackface() is enabled. 





PICbackface(mode) 
int mode; 
mode = _ PIC_ONor PIC_OFF 


PiCzbuffer_lines() 


The PICzbuffer_lines() functions controls whether lines are zbuffered or not. Zbuffered lines are 
aliased and can be rendered as depth-cued or current color lines. PICinit() initializes zbuffered 
lines to PIC_OFF. 


Because non-zbuffered lines are more efficient than zbuffered lines, it is recommended 
that you use PICzbuffer_lines(PIC_OFF) when zbuffering is not required. 





PICzbuffer_lines(mode) 
int mode; 
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mode =  PIC_ON or PIC_OFF 





3-136 PIClib User’s Guide, Version 1.2 





Antialiasing 


The Antialiasing functions allow you to eliminate jagged lines or edges in the objects of your 
scene. This section discusses the following functions: 


= PiCantialias lines(mode) 

m PICinit_sampling(xsamples,ysamples,xscale,yscale,filter) 
= PICenter sampling _pass() 

mw PICexit_sampling pass(Q) 


PICexit_sampling()) uses the external z memory, and therefore can be used only on 


Antialiasing by supersampling (PICinit_sampling(), PICenter_sampling() and 
NOTE 
pore models 932 and higher in high resolution mode and on all models in NTSC mode. 


PlCantialias lines() 


The PICantialias lines() function determines whether lines are to be antialiased. To antialias an 
object, use the PICinit_sampling(), PICenter_sampling pass() and PICexit_sampling pass() 
functions described below. 


PICantialias_lines(mode) 
int mode; 


mode = PIC ONorPIC_OFF 


PiCinit_sampling() 


PICinit_sampling() initializes super-sampling mode for use in antialiasing objects. Based on the 
arguments passed to it, PICinit_sampling() returns the number of sampling passes required on the 
scene. The arguments xsamples and ysamples are the number of samples in x and y, respectively, 
to take per pixel. The samples can be taken over a section of pixels, depending on xscale and 
yscale. For one pixel coverage, xscale and yscale should each be 1.0. Different filters can be 
defined for use in filtering the samples. The filter parameter should be an array of size (xsamples * 
ysamples). 


The return value npass should be used to control the loop over the scene description with calls to 
PICenter_sampling pass() and PICexit_ sampling pass() at the beginning and end of each 
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iteration. 


If amode = PIC_OFF, alpha matte generation is ignored. If amode = PIC_ON, an alpha matte is 
generated for the image. To generate an alpha matte correctly, the image must be Phong shaded. 


If the function is called on a model 916 or a model 920 in high resolution mode, the return value 
will be zero. 


Because this function uses external z-memory, it can only be used with Pixel Machine 
models 932 and higher in high resolution mode, and on all models in NTSC mode. 





xsamples,ysamples = the number of sampling points in the x and y directions 
xscale,yscale = pixel scale factor. 
filter = a matrix of size (xsamples x ysamples) which stores the coefficients 


to be applied to the samples 


amode = PIC_ON — an alpha matte is generated for the image 
PIC_OFF — alpha matte generation is ignored 





PiCenter_ sampling pass() 


The PICenter_sampling pass() function marks the beginning of a sampling pass. This command 
alters the projection matrix. 


Remember to initialize the frame buffer and the z buffer before rendering the scene. 
(This can be done with any of the clear or copy functions). 





PICenter_sampling pass() 
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PICexit_ sampling pass() 


The PICexit_ sampling pass() marks the end of a sampling pass. This command restores the pro- 
jection matrix. 





PICexit_ sampling pass() 





Example: 


_ (XSAMPLES * YSAMPLES) 


4,0 
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The Video functions allow you to manipulate the color lookup tables and query their current status. 
This section discusses the following functions: 


« PICupdate_map(mode) 

a PICput_color_map(red,green,blue) 

= PICput_color_map_entry(index,red,green,blue) 
a PICput_alpha_map(red,green,blue) 

w# PICput_alpha_map_entry(index,red,green,blue) 
m PICget color map(red,green,blue) 

aw PICget color map_entry(index,red,green,blue) 

@ PICget_alpha_map(red,green,blue) 

a PICget_alpha_map_entry(index,red,green,blue) 


PiCupdate_map() 


The PiCupdate_map() function displays immediately any changes made to the video. The function 
is enabled by specifying the PIC_ON mode. When PIC_OFF, changes to the video are not visible 
until the function is re-enabled. 


Whenever altering any of the color tables, it is suggested that you first call 


PICupdate_map(PIC_OFF), and then call PICupdate_map(PIC_ON) after all your changes are 
complete. 


PiCupdate_map(mode) 
int mode; 


mode =  PIC_ON or PIC_OFF 
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PiCput_color_map() 


The PICput_color_map() function loads an entire lookup table for each rgb channel. The values 
contained in these tables are in normalized form (between 0.0 and 1.0). 





PICput_color_map(red,green,blue) 
float *red,*green,*blue; 


PiCput_color map_entry() 


The PICput_color_map_entry() function loads a specified entry into the rgb color map. Index 
can range from 0 to PIC_VIDEO_TABLE - 1. 





PICput_color_map_entry(index,red,green,blue) 
int index; 
float red,green,blue; 


index = _ indicates which entry is being updated 


PiCput_alpha_map() 


The PICput_alpha_map() function loads an entire lookup table for the alpha channel. 


PICput_alpha_map(red,green,blue) 
float *red,*green,*blue; 
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PlCput_alpha_ map entry() 


The PiCput_alpha_map_entry() function loads a specified entry in the color map for the alpha 
channel. index can range from 0 to PIC_VIDEO TABLE - 1. 





PICput_alpha_map_entry(index,red,green,blue) 
int index; 
float red, green, blue; 


index = _ indicates which entry is being updated 





PiCget_color map() 


The PICget_color_map() function returns arrays of r, g, and b values from the current rgb lookup 
map. These arrays (red, green, and blue) are of length PIC_VIDEO_TABLE. 





PICget_color_map(red,green,blue) 
float *red,*green,*blue; 





PiCget_color map entry() 


The PICget_color_map_entry() function returns a specified rgb entry from the current rgb lookup 
table. index can range from 0 to PIC_VIDEO TABLE - 1. 





PICget_color_map_entry(index,red,green,blue) 
int index; 
float *red,*green,*blue; 
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PiCget_alpha_map() 


The PICget_alpha_map() function returns arrays for the current r, g, and b values in the alpha 
map. Each red, green, and blue array is of length PIC_VIDEO TABLE. 


PiCget_alpha_map(red, green, blue) 
float *red,*green,*blue; 


PiCget_alpha map entry() 


The PICget_alpha_map_entry() function returns a specified rgb alpha map entry. index can range 
from 0 to PIC_VIDEO_TABLE - 1. 


PICget_alpha_map_entry(index,red,green,blue) 
int index; 
float *red,*green,*blue; 
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The Raster Operations functions manipulate the intensities of pixels by adding, subtracting, or 
multiplying them by a constant value. This section discusses the following functions: 


mw PICpixel_add(red,green,blue,alpha) 
mu PICpixels_multiply(red,green,blue,alpha) 


PiCpixel_add() 


The PICpixel_add() function adds a constant value to the intensities of all pixels in the current 
viewport. 





PICpixel_add(red,green,blue,alpha) 
float red,green,blue,alpha; 


red,green,blue,alpha = the rgb and alpha values to be added to the pixel values 





PiCpixel_multiply() 


The PICpixel_multiply() function multiplies the intensities of pixels in the current viewport by a 
constant value. 


PICpixel_multiply(red,green,blue,alpha) 
float red,green,blue,alpha; 


red,green,blue,alpha = the rgb and alpha values to be multiplied by the pixel values 
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The Input Device functions let you control the operation of a mouse; query the state of a button, a 
valuator, or the current value of a 2D locator; query the event queue and sample keyboard buttons; 
and define a cursor and move it with or without the mouse. The functions discussed in this section 
are: 


a PICattach_mouse() gw PICqueue_events(mode) 

m PICdetach_mouse() w PICget_event(event,value) 

gm PICget_button(button) a PICdisplay_cursor(mode) 

m@ PICget_valuator(valuator) a PICdefine_cursor(cursor) 

w PICget_locator(x,y) # PICposition_cursor(ix,iy) 

m PICquery_queue(event,value) = PICwait_event(event,value) 

# PICflush_queue() aw PICget host_screen_size(width,height) 


m PICput_ mouse _ playground (left,right,top,bottom) 


PiCattach_mouse() 


The PICattach_mouse() function initializes the mouse and must be called before any other Input 
Device function. 


PICattach_mouse() 


PiCdetach_mouse() 


The PICdetach_mouse() function terminates the operation of the mouse and must be the last Input 
Device function called. 


PICdetach_mouse() 
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PiCget_button() 


The PICget_button() function returns the state of a mouse button indicated by the argument but- 
ton. If the button is currently pressed, the function returns a value of PIC_TRUE; if not, returns a 
value of PIC_FALSE. 





PiICget_button(button) 
int button; 


button = PIC_LEFTMOUSE 
= PIC_RIGHTMOUSE 
PIC_MIDDLEMOUSE 


H 





PiCget_valuator() 


The PICget_valuator() function returns the current value of a valuator. 





PiCget_valuator(valuator) 
int valuator; 


valuator = PIC_XMOUSE,PIC_YMOUSE 


PiCget_locator() 


The PICget_locator() function returns the current value of a locator’s x and y position. The return 
values are stored in the locations pointed to by x and y respectively, 





PICget_locator(x,y) 
int *x, *y; 
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The Input Device functions let you control the operation of a mouse; query the state of a button, a 
valuator, or the current value of a 2D locator; query the event queue and sample keyboard buttons; 
and define a cursor and move it with or without the mouse. The functions discussed in this section 
are: 


m PICattach_mouse() m= PICqueue_events(mode) 

a PICdetach_mouse() aw PICget_event(event,value) 

m PICget_button(button) m PICdisplay_cursor(mode) 

mw PICget_valuator(valuator) w PICdefine_cursor(cursor) 

w PICget_locator(x,y) w PICposition_cursor(ix,iy) 

mw PICquery_queue(event,value) g PICwait_event(event,value) 

@ PICflush_queue() mw PICget_host_screen_size(width,height) 


a PICput_mouse_playground(eft,right,top,bottom) 


PiCattach_mouse() 


The PICattach_mouse() function initializes the mouse and must be called before any other Input 
Device function. 


PICattach_mouse() 


PiCdetach_mouse() 


The PICdetach_mouse() function terminates the operation of the mouse and must be the last Input 
Device function called. 


PICdetach_mouse() 
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PiCget_button() 


The PICget_button() function returns the state of a mouse button indicated by the argument but- 
ton. If the button is currently pressed, the function returns a value of PIC_TRUE; if not, returns a 
value of PIC_FALSE. 


PiCget_button(button) 
int button; 


button = PIC_LEFTMOUSE 
= PIC_RIGHTMOUSE 
PIC_MIDDLEMOUSE 





PiCget_valuator() 


The PICget_valuator() function returns the current value of a valuator. 


PICget_valuator(valuator) 
int valuator; 


valuator = PIC_XMOUSE,PIC_YMOUSE 





PiCget_locator() 


The PICget_locator() function returns the current value of a locator’s x and y position. The return 
values are stored in the locations pointed to by x and y respectively. 





PICget_locator(x,y) 
int *x, *y; 
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XY = the x and y coordinates of the location. 





PiCqueue_events() 


The PICqueue_events() function enables and/or disables the event queuing process. 


PICqueue_events(mode) 
int mode; 


mode = PIC_ON or PIC_OFF. 


PiCget_event() 


The PICget_event() function returns an event and its value. The return values are stored in the 
locations pointed to by x and y respectively. The PICqueue_events() function must be called to 
enable the queuing process before this function can be invoked. The possible events that can occur 
and their possible values are as follows: 











PIC_LEFTMOUSE 
PIC_RIGHTMOUSE 
PIC_MIDDLEMOUSE 
PIC_XMOUSE 
PIC_YMOUSE 
PIC_KEYBOARD 


PIC_UP PIC_DOWN 
PIC_UP PIC_DOWN 
PIC_UP PIC_DOWN 


X screen coordinate 










y screen coordinate 





keyboard event code 





PICget_event(event,value) 
short *event, *value; 
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PiCdisplay_cursor() 


The PICdisplay_cursor() function displays a cursor on the screen at a specified location. 


PICdisplay_cursor(mode) 
int mode; 


mode = PIC_ON or PIC_OFF. 


PiCdefine_cursor() 


The PICput_cursor() function defines a cursor to be displayed on the screen. The cursor is 
attached to the mouse input device and can be moved by moving the mouse. 


The cursor is defined according to the PlICcursor data structure. See Appendix B for a definition of 
the PlCcursor structure. Once a cursor is defined, it can be displayed on the screen with the 
PICdisplay_cursor() function. 








PICdefine_cursor(cursor) 
PICcursor *cursor; 


cursor =  32x4 byte array with a center point at initx,inity. 


PiCposition_cursor() 


The PICposition_cursor() function positions the cursor on the screen. 





PICposition_cursor(ix,iy) 
int ix, iy; 
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ix,iy = the x and y screen coordinates of the position 





PiCquery queue() 


The PICquery_queue() function returns the state of the queue without altering the queue. The 
next event and value are returned in the location pointed to by event and value. A return event of 0 
indicates that the queue is empty. 


Event queuing must be enabled before invoking PICquery_queue(). To enable event queuing use 
the PICqueue_events() function. 


PICquery_queue(event,value) 
long *event, *value; 


event = __ the event that occurred 


value = __ the value associated with the event 


PiCwait_event() 


The PICwait_event() function waits for a particular event to occur. The value of the event param- 
eter indicates which event to wait for. A value of PIC_ANY EVENT causes the function to return 
after any event occurs. The event and value of the event that occurred are stored in the location 
pointed to by event and value respectively. 


Event queuing must be enabled before invoking PICwait_event(). To enable event queuing use 
the PICqueue_events() function. 


PiICwait_event(event,value) 
long *event, *value; 
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event PIC_LEFTMOUSE 
PIC_RIGHTMOUSE 
PIC_MIDDLEMOUSE 
PIC_XMOUSE 
PIC_YMOUSE 
PIC_KEYBOARD 


PIC_ANY_ EVENT 


the value of the event 


how ob i uw wou 


value 





PiCflush_queue() 


The PICflush_queue() function clears the event queue. Event queuing must be enabled before 
invoking PICflush_queue(). To enable event queuing use the PICqueue_events() function. 





PICflush_queue() 


PiCget_host_screen_size() 


The PICget_host_screen_size() function retums the x and y dimensions of the host screen. The 
width and height of the screen are stored in the locations pointed to by width and height respec- 
tively. 


PICget_host_screen_size(width,height) 
long *width, *height; 


width = _ the x screen dimension in pixels 


height = __ the y screen dimension in pixels 
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PiCput mouse_playground() 


The PICput_mouse_playground() function initializes the mouse playground window. If this 
function is not called before the PICattach_mouse() function, the coordinates of the mouse play- 
ground will default to a pre-determined size and location. 


PICput_mouse_playground(left,right,top,bottom) 
int left, right, top, bottom; 


left = the left x position of the playground in pixels 
right = the right x position of the playground in pixels 
top = the top y position of the playground in pixels 
bottom = __ the bottom y position of the playground in pixels 
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The Picking and Selecting functions enter and exit picking and selecting mode and manipulate 
the picking and selecting identifier stack. The identifier stack is used in picking and selecting opera- 
tions. 


The functions described in this section are: 


m PiCattach_picking(nbuff,nstack) m PiCinit_identifier_stack() 

mw PICdetach_picking() = PICpop_identifier() 

w PICenter_ picking mode(x,y) a PICpush_identifier(id) 

a PICenter_selecting mode() a PICput_identifier(id) 

g@ PICexit_picking mode() w PICput_picking region(dx,dy) 


mw PICexit_selecting mode() 


PiCattach_picking() 


The PICattach_picking() function starts the picking and selecting process, allocates space for the 
picking buffer and identifier stack, initializes a data structure of type PlCbuffer and returns a 
pointer to that structure. This function must be called before any other Picking or Selecting function. 
The size of the picking/selecting buffer is specified by nbuffer; the size of the identifier stack is 
specified by nstack. For a definition of the PlCbuffer structure, see Appendix B. 


PICattach_picking(nbuffer,nstack) 
int nbuffernstack; 





nbuffer = __ the size of the buffer 
nstack = the size of the stack 
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PiCdetach_picking() 


The PICdetach_picking() function terminates the picking and selecting process started by the 
PICattach_picking() function. PICdetach_picking() also frees the PlCbuffer structure allocated 
by the PICattach_picking() function, the picking/selecting buffer, and the identifier stack. This 
function must be the last Picking or Selecting function called. 


PICdetach_picking() 


PiCenter_ picking mode() 


The PICenter_picking mode() function enables picking mode. During picking mode no objects 
are rendered on the screen. Once picking mode is entered, if an identifier hits the picking region, 
the size of the identifier stack and its contents are written to the buffer. The buffer can be accessed 
through the PlCbuffer() structure returned from a PICattach_picking() call. 


PICenter_picking mode() takes as arguments the coordinates of the center of the picking region. 
To specify the size of this region, use the PICput_picking region() function described below. 


Note that atoms cannot be used as identifiers. 


PICenter_picking_mode(x,y) 
int x,y 


xy = the x,y location indicating the center of the picking region 
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PilCenter_selecting mode() 


The PICenter_selecting mode() function enables selecting mode. During selecting mode no 
objects are rendered on the screen. Once selecting mode is entered, if an identifier hits the selecting 
region, the size of the identifier stack and its contents are written to the buffer. The buffer can be 
accessed through the PlCbuffer structure returned from a PICattach_picking() call. 


The selecting region is the 3D volume specified by the current viewing projection. The viewing 
projection must be specified before entering selecting mode. 


Note that atoms cannot be used as identifiers. 








PICenter_selecting mode() 





PlCexit_picking mode() 


The PICexit_picking mode() function exits picking mode. The picking/selecting buffer and the 
identifier stack are freed. 





PICexit_picking mode() 


PiCexit_selecting mode() 
The PICexit_selecting mode() function exits selecting mode. The picking/selecting buffer and 


the identifier stack are freed. 


PICexit_selecting mode() 
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PiCinit_ identifier stack() 


The PICinit_identifier_stack() function initializes the identifier stack used in picking and selecting 
operations. This function is automatically performed when picking/selecting mode is entered, but 
can be used to reinitialize the identifier stack. 


PICinit_identifier_stack() 


PiCpop _identifier() 


The PICpop_identifier() function pops the top identifier from the identifier stack. 





PICpop_identifierQ 





PiCpush_identifier() 


The PICpush_identifier() function pushes the identifier stack and places the identifier defined by 
the argument id on the top of the stack. 


PICpush_identifier(id) 
int id; 


id = identifier 
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PiCput_identifier() 


The PICput_identifier() function replaces the top of the identifier stack with the identifier defined 
by the argument id. 


PICput_identifier(id) 
int id; 


id = identifier 


PiCput_picking region() 


The PICput_picking region() function sets the size of the picking region to a rectangle specified 
by the dx and dy arguments. 





PICput_picking region(dx,dy) 
int dx,dy; 


dx,dy = __ the size of the picking region rectangle in pixels 
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Constant Value 
PIC_FALSE 0 
PIC_TRUE 1 
PIC_OFF 0 
PIC_ON 1 
PIC_ERR_OK 0 
PIC_ERR ARG 1 
PIC_ERR_OPEN 2 
PIC_ERR_ NODE 3 
PIC_ERR FILE 4 
PIC_ERR_LOAD 5 
PIC_ERR_INVERSE 6 
PIC_BEZIER_BASIS 0 
PIC_HERMITE_BASIS 1 
PIC_FOUR_POINT BASIS 2 
PIC_B_SPLINE_BASIS 3 
PIC_USER_BASIS_0 0 
PIC_USER_BASIS 1 1 
PIC_USER_BASIS 2 2 
PIC_USER_BASIS 3 3 
PIC_USER_BASIS 4 4 
PIC_USER_BASIS 5 5 
PIC_USER_BASIS 6 6 
PIC_USER_BASIS 7 7 
PIC_EUCLID_POINT 1 
PIC_EUCLID_ LINE 2 
PIC_EUCLID_ POLYGON 3 
PIC_EUCLID_ TEXTURE 4 
PIC_SCREEN_PIXELS 1280 
PIC_SCREEN LINES 1024 
PIC_IMAGE_PIXELS 2048 
PIC_IMAGE_LINES 2048 
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PIC_SINGLE_BUFFER 0 
PIC_DOUBLE BUFFER 1 
PIC_BUFFER_ZERO 0 
PIC_BUFFER ONE 1 


PIC_BUFFER_OVERFLOW | 1 
PIC_STACK_OVERFLOW | 2 
PIC_STACK_UNDERFLOW | 3 


#ifdef _FI7_ 
PIC_TOP_BUFFER (2*16*16) 
PIC BOTTOM BUFFER ((2*16+8)* 16) 
PIC_SCREEN BUFFER (6* 16*16) 
#else 

PIC_TOP_BUFFER 0x0200 

PIC BOTTOM | BUFFER 0x0280 

PIC “SCREEN - BUFFER 0x0600 
#endif 


PIC_LIGHT DIRECT 1 
PIC_LIGHT_POINT 2 
PIC_LIGHT_ SPOT 3 
PIC_LIGHT_CONE 4 


PIC_TYPE_ALL Al 
PIC_LIGHT ALL 1 
PIC_BLACKOUT PIC_OFF 
PIC_SUNGLASSES PIC_ON 


PIC_SHADE_OFF 0 
PIC_SHADE_FLAT 1 
PIC_SHADE_GOURAUD 2 
PIC_SHADE_PHONG 3 
PIC_SHADE_DEPTH 4 


PIC_MAX BASIS 8 
PIC_MAX_TRANSFORM 32 
PIC_MAX_VIEWPORT 32 
PIC_MAX_DIR_LIGHT 50 
PIC_MAX_PNT_ LIGHT 50 
PIC_MAX_SPOT_LIGHT 50 
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PIC_MAX_POLY_PNTS 


PIC_ARC_DEFAULT 
PIC_CIRCLE_DEFAULT 
PIC_CURVE_DEFAULT 
PIC_QUADRIC_DEFAULT 
PIC_PATCH_ DEFAULT 


PIC_LOW 

PIC_MEDIUM 

PIC_HIGH 
PIC_TEXTURE_DEFAULT 


PIC_ZMIN_DEFAULT 
PIC_ZMAX_DEFAULT 


PIC_INTENSITY 
PIC_IINTENSITY 


PIC_VIDEO_ TABLE 


PIC_BLACK 
PIC_RED 
PIC_GREEN 
PIC_BLUE 
PIC_YELLOW 
PIC_MAGENTA 
PIC_CYAN 
PIC_WHITE 


#ifndef PIC_RGB PIXELS 

PIC_RGB_ PIXELS 

PIC_ RGB_ PACKED PIXELS 

PIC_ RGBA_ PIXELS ~ 

PIC_ RGBA_ PACKED PIXELS 

PIC | _ABGR_ PACKED PIXELS 

PIC_ RGB _ ENCODED_ PIXELS 

PIC_ RGB_ PACKED _ENCODED_ PIXELS 
#endif 


PIC_EXTENDED_VRAM 
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1 
4 
PIC_LOW 

-1,0¢+00 

0.0¢+00 

32767.0 
(1.0/PIC_INTENSITY) 
256 

0.0,0.0,0.0 

1.0,0.0,0.0 

0.0,1.0,0.0 

0.0,0.0,1.0 

1.0,1.0,0.0 

1.0,0.0,1.0 


0.0,1.0,1.0 
1.0,1.0,1.0 


11 
12 
15 


13 


Oxf0 
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PIC_OVERLAY_OFF 
PIC OVERLAY _ NON_ZERO 
PIC OVERLAY _ HIGH | BIT 


PIC_NO_ COMPOSITE 
PIC_A OVER B 
PIC_B OVER A 
PIC AINB 
PIC B_ Lem 
PIC_A_OUT 
PIC B nob cA 
PIC_A_ATOP B 
PIC_B ATOP_A 
PIC_A_XOR B 
PIC_PLUS 
PIC_A PLUS B 


PIC_SPHERE_TEMPLATE 
PIC_UD_TEMPLATE 

PIC | ~MAX _UDTEMPLATE 
PIC_ ~MAX_ _STEMPLATE 
PIC | MAX | STAMP 


PIC_BROADCAST_VRAM 
PIC | _BROADCAST . ZRAM 


PIC_READ_ONLY 
PIC_WRITE ONLY 


PIC_ANY_EVENT 
PIC_LEFTMOUSE 
PIC_MIDDLEMOUSE 
PIC_RIGHTMOUSE 
PIC_XMOUSE 
PIC_YMOUSE 
PIC_KEYBOARD 


PIC_UP 
PIC_DOWN 


DEVcursor 


PIC_PIXEL_PHONG 
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Wr © 


CeINAKNRWNHO 


id 
Ooo 


0 
1 

256 
(PIC_MAX_UDTEMPLATE/2) 
19 


0 
1 


Wh 


NANKRWNK OC 


1 
PlCcursor 
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typedef float © PlCmatrix[4][4]; 


typedef struct { 


int initx, inity; 
int bitmap[32]; 
} PlCcursor; 


typedef struct { 

float x, y, Z; 

float nx, ny, nz; 

float r, g, b; 

float exp, angle; 
float — intensity; 
long samples, vertices; 
float “vertex; 

} PIClight_source; 


typedef struct { 

float a_red, a_green, a_blue; 
float d_red, d_green, d_blue; 
float s_red, s_ green, s_blue; 
float exp; 
float transparent; 
float dissolve; 
float reflectivity; 
float refraction_index; 
float t_red, t_green, t_blue; 

} PiCsurface_model:; 


typedef unsigned char PICpixel; 


typedef struct { 


PiCpixel red, 
green, 
blue; 

} PlCrgb_pixel; 


typedef struct { 
PiCpixel red, 
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green, 
blue, 
alpha; 
} PlCrgba_pixel:; 


typedef struct { 
PiCpixel alpha, 


blue, 
green, 
red; 
} PiCabgr_pixel; 
typedef struct { 
int *buffer; 
int *nused; 
int *buffer_overflow; 
int *stack_overflow; 
int *stack_underflow; 


} PiCbuffer; 


#define PIC_RASTER_DISPATCH 256 


typedef struct { 


short magic; /* Magic number VFONT_MAGIC */ 
unsigned short size;/* Total # bytes of bitmaps */ 

short maxx; /* Maximum horizontal glyph size */ 
short maxy; /* Maximum vertical glyph size */ 
short xtend; /* (unused) */ 


} raster_header; 


typedef struct { 
unsigned short addr[PIC_RASTER_ DISPATCH]; 
short nbytes[PIC_RASTER_DISPATCH]; 
char ‘data; 
} raster_font; 


typedef struct { 
raster header header; 
short twobytes; /* For aligning (char*)data below */ 
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raster_font font; 
} PiCraster_font; 


#define PIC VECTOR_FONT SIZE 95 


typedef struct { 


short mm; 
short pt; 
short Lw; 
short Rw; 


} vector_font; 


typedef struct { 
vector_font ptr[PIC_VECTOR_FONT SIZE]; 
char  ‘“*hshstr; 
} PlCvector_font; 


typedef struct 


short _ type; I sphere or user defined */ 
int ix; I" template position in vram in x */ 
int iy; /* template position in vraminy */ 
int size; P size of template in pixels */ 
float radius; * size of radius (spheres only) */ 


} PiCtemplate; 
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FUNCTION 


PICalpha (3) 
PICantialias_ lines (3) 
PICarc (3) 

PICarc_ precision (3) 
PICatom (3) 
PICatom_light (3) 
PICatom_surface (3) 
PiCattach_mouse (3) 
PICattach_picking (3) 
PICbackface (3) 
PICbroadcast_data (3) 
PICcamera_view (3) 
PICcircle (3) 
PICcircle_precision (3) 
PiCclear_alpha (3) 
PICclear_rgb (3) 
PICclear_rgbz (3) 
PICclear_z (3) 
PICclockwise (3) 
PICcolor_alpha (3) 
PICcolor_rgb (3) 
PICcomposite_mode (3) 
PICcopy_back_to_ext (3) 
PICcopy_back_to_front (3) 
PICcopy_ext_to_back (3) 
PICcopy_ext_to_z (3) 
PICcopy_front_to_back (3) 
PICcopy_z_to_ ext (3) 
PiCcurve geometry 3d (3) 
PICcurve_precision (3) 
PICdefine_cursor (3) 
PICdepth cue (3) | 
PICdepth_cue_limits (3) 
PICdetach_mouse (3) 
PICdetach_picking (3) 
PICdisplay_cursor (3) 
PICdisplay_overlay (3) 
PICdouble_buffer (3) 
PICdraw (3) 

PICdsp float (3) 
PiCenter_picking mode (3) 


Appendix C 


DESCRIPTION 


- enable/disable writing to the alpha channel 

- enable/disable the antialiasing of lines 

- draw a circular arc 

- set precision of arc 

- draw a spherical atom 

- specify a light source for a spherical atom 

- specify a surface model for a spherical atom 

- attach a mouse 

- start picking/selecting process 

- enable/disable backface removal mode 

- broadcast a buffer of data to pixel-node memories 
- define a viewing transformation in terms of pan, tilt, and swing angles 
- draw a circle 

- set precision of circle 

- clear the alpha channel of current viewport 

- clear the rgb channels of current viewport 

- clear rgb and z depth of current viewport 

- clear z depth of current viewport 

- enable/disable normal vector definition in clockwise direction 
- define the current alpha color 

- define the current rgb color 

- set the current image compositing mode 

- copy the back buffer to an extended screen buffer 
- copy back buffer to front buffer 

- copy an extended screen buffer to the back buffer 
- copy extended screen z buffer to screen z buffer 
- copy front buffer to back buffer 

- copy z buffer to the extended z buffer 

- draw a 3D curve 

- set precision of curve 

- define the current cursor 

- enable/disable depth cueing 

- set z limits and color range of depth cueing 

- terminate mouse process 

- terminate picking/selecting process 

- enable/disable cursor display 

- enable/disable display of the alpha channel 

- enable/disable double buffer mode 

- draw a line 

- enable/disable DSP32 floating point format 

- enter picking mode 
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FUNCTION 


PICenter_sampling pass (3) 
PICenter selecting mode (3) 


PICeuclid_mode (3) 
PICexit (3) 
PICexit_picking mode (3) 
PICexit_sampling_pass (3) 


PICexit_selecting_ mode (3) 


PICflip (3) 
PICflush_queue (3) 
PICget_alpha_map (3) 


PICget_alpha_map entry (3) 


PICget_buffer (3) 
PICget_buffer mode (3) 
PICget_button (3) 
PICget_color_map (3) 


PICget_color_map entry (3) 


PICget_depth (3) 
PICget_event (3) 


PICget_ host_screen size (3) 


PICget_image header (3) 
PiICget_inverse_project (3) 





DESCRIPTION 








- Start a super-sampling pass 

- enter selecting mode 

- set drawing mode 

- exit the PICIib library 

- exit picking mode 

- end a super-sampling pass 

- exit selecting mode 

- enable/disable normal vector reversal 

- flush event queue 

- get current rgb entries from alpha map 

- get a specified rgb alpha map entry 

- get the number of the current display buffer 
- get buffer mode (single or double) 

- query current state of button 

- get current rgb color map 

- get one rgb color map entry 

- get the near and far depth limits 

~ return an event and its value 

- returns the dimensions of the host screen 

- read the Pixel Machine image header from a file 
- get the inverse of the current projection matrix 


PICget_inverse_transform (3) - get the inverse of the current transformation matrix 


PiCget_locator (3) 


- query the current value of a locator 


PICget_normal_ transform (3) - get normal vector transformation matrix 


PICget overlay_mode (3) 
PICget_project (3) 
PICget_scan_line (3) 
PICget_screen size (3) 
PICget_shade_mode (3) 
PICget_template (3) 
PiCget_transform (3) 
PiCget_valuator (3) 
PICget_viewport (3) 
PICimage_header (4) 
PICinit (3) 
PICinit_identifier_stack (3) 
PICinit_sampling (3) 
PIClight_ambient (3) 
PIClight switch (3) 
PIClookat_view (3) 
PIClookup_ view (3) 
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- get the pixel node overlay 

- get the current projection matrix 

- read a scan line of pixels from the screen 

- return the current screen size 

- return current shading mode 

- get a previously defined template 

- get the current transformation matrix 

- returns the current value of a valuator 

- return the current viewport’s definition 

- format of a Pixel Machine image header file 

- initialize and reset the PIClib library 

- initialize identifier stack 

- initialize super-sampling mode 

- set the ambient light’s intensity value 

- turn all or one light source on or off 

- define a viewing transformation in terms of viewpoint, reference point and twist angle 
- define a viewing transformation in terms of viewpoint, reference point and twist angle 
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PICmake_sphere_template (3) - create a sphere template 


PICmake_template (3) - create a user defined template 

PICmove (3) - move to a given point 

PICopen_raster_font (3) - select a raster font type 

PICopen_vector_font (3) - select a vector font type 

PICortho_project (3) - define an orthographic projection 

PICoverlay_mode (3) - select overlay mode to display the alpha channel 
PICpatch_geometry_3d (3) - draw a 3D surface patch 

PICpatch_precision (3) - set precision of patch 

PICpercent_texture (3) - determines the texture map’s intensity value at each pixel 
PICpersp_project (3) - define a 3D perspective viewing pyramid 

PICpixel_add (3) - add a constant value to pixels in current viewport 
PICpixel_multiply (3) - multiply pixels in the current viewport by a constant 
PICpoint (3) - draw a point 

PICpolar_view (3) - define view point and view direction in Polar Coordinates 
PICpoly_ close (3) - close a polygon 
PICpoly_normal (3) - define a polygon normal vector 

PICpoly_point (3) - draw a polygon 

PICpoly_point_nv (3) - draw a 3D polygon with normal vectors 
PICpoly_point_nv_uv (3) - draw a 3D polygon with normal vectors and texture indices 
PICpoly_point_rgb (3) - draw a 3D polygon with rgb color 

PICpoly_point_uv (3) - render a 3D polygon with texture indices 

PICpop_ identifier (3) - pop top identifier from identifier stack 

PICpop_project (3) - replace the current projection matrix with the top of the projection stack 
PICpop_transform (3) - replace the current transformation matrix with the top of the transformation stack 
PICpop_viewport (3) - replace the current viewport with the top of the viewport stack 
PICposition_cursor (3) - position cursor (in Pixel Coordinates) 


PICpostmultiply_project (3)  - post-multiply the current projection matrix by a specified matrix 
PICpostmultiply_transform (3)- post-multiply the current transformation matrix by a specified matrix 


PICpremultiply project (3) - pre-multiply the current projection matrix by a specified matrix 
PICpremultiply_transform (3) - pre-multiply the current transformation matrix by a specified matrix 
PICpush_identifier (3) - push an identifier on identifier stack 

PICpush_project (3) - copy the current projection matrix onto the top of the projection stack 
PICpush_transform (3) - push transformation matrix onto the top of the transformtion stack 
PiCpush_viewport (3) - copy the current viewport onto the top of the viewport stack 
PICput_alpha_map (3) - load the entire lookup table for the alpha channel 
PIiCput_alpha_map_ entry (3) - load a single entry in the lookup table for the alpha channel 
PICput_basis (3) - define a basis matrix 

PICput_color_ map (3) - load entire lookup table for each rgb channel 
PICput_color_map_entry (3) - load a specific entry into the rgb color map 

PICput_depth (3) - set the near and far depth limits 
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FUNCTION DESCRIPTION 

PICput_identifier (3) - replace the top of identifier stack 
PICput_identity_transform (3) - load the current transformation matrix with the identity matrix 
PICput_image_header (3) - write a Pixel Machine image header to a file 

PICput_light source (3) - load a light source 

PICput_mouse_playground (3)- initializes mouse playground window 
PICput_overlay_mode (3) - load overlay code into the pixel nodes 

PICput_picking region (3) _- set the size of picking region 

PICput_project (3) - load current projection transformation matrix with a specified matrix 
PICput_raster_font (3) - set the current raster font 

PICput_scan_line (3) - write a scan line of pixels to the screen 
PICput_surface_model (3) - specify a surface shading model 

PICput_texture (3) ~ define an area of offscreen memory to be used as a single texture 
PICput_transform (3) - load the current transformation matrix with a specified matrix 
PICput_vector_font (3) - set the current vector font 

PICput_viewport (3) - set the current viewport 

PICquadric_ precision (3) - set precision of quadrics and superquadrics 

PICquery queue (3) - query event queue 

PICqueue_events (3) - enable/disable event queueing 

PICraster_font_text (3) - write a text string using the specified raster font 
PICraster_text (3) - write a text string using the current raster font 

PICrectangle (3) - draw a rectangle 

PICreset (3) - reset graphical parameters to default values 
PICreset_texture (3) - set the current area to be used for texture mapping with the default values 
PICresume (3) - initialize the PICIib library 

PICrotate (3) - apply a rotation transformation to all objects 

PICscale (3) - apply a scaling transformation to all objects 
PICselect_curve_basis (3) - select the basis matrix used in drawing curves 
PICselect_patch_basis (3) - select the basis matrix to be used in drawing patches 
PICset_texture (3) - set the current texture mapping area 

PICshade_mode (3) - select a shading mode 

PICsphere (3) - draw a unit sphere 

PICstamp_template (3) ~ Stamp a buffer of templates on the screen 

PICsuperq ellipsoid (3) - draw a superquadric ellipsoid 

PICsuperq hyper! (3) - draw a superquadric hyperboloid of 1 sheet 
PICsuperq_hyper2 (3) - draw a superquadric hyperboloid of 2 sheets 

PICsuperq toroid (3) - draw a superquadric toroid 

PICswap_buffer (3) - swap displayable buffers 

PICswap_pipe (3) - swaps Transformation Pipes in dual-pipe configurations 
PiCtexture_precision (3) ~ Set texture map precision of textured perspective polygons 
PICtranslate (3) - apply a translation transformation to all objects 
PICupdate_map (3) - enable/disable updating of video lookup tables 
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FUNCTION 


PICvector_font_text (3) 
PICvector_text (3) 
PICwait_event (3) 
PICwait_psync (3) 
PICwait_vsync (3) 
PICwindow project (3) 
PICzbuffer (3) 
PICzbuffer_lines (3) 
picalpha (1) 

picbars (1) 

picboot (1) 
picbroadv (1) 
picbroadz (1) 
picbtof (1) 

picdisp (1) 

picetof (1) 

picftob (1) 

picftoe (1) 
picgamma (1) 
picinit (1) 

piclear (1) 

piclens (1) 

picsave (1) 
pictexture (1) 
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DESCRIPTION 


- write a text string using the specified vector font 

- write a text string using current vector font 

- wait for a specifed event to occur 

- wait for Pixel Node processor sync 

- wait for a vertical sync 

- define a 3D perspective projection 

- enable/disable zbuffer mode 

- enables/disables zbuffering of lines 

- turn the display of the alpha channel on or off 

- display color bars on the screen 

- load the PIClib modules into the geometry and drawing nodes 
- broadcasts a buffer of data to the pixel node memory 

- broadcasts a buffer of data to the pixel node memory 

- copy contents of the back buffer to the front buffer 

- download and/or display an image 

- copy the contents of the extended VRAM buffer to the front buffer 
- copy the contents of the front buffer to the back buffer 

- copy the contents of the front buffer to extended VRAM 

- create gamma corrected lookup tables 

- resets the Pixel Machine to its default values 

- Clear the screen 

- interactive tool that roams around and magnifies the display 
- Save an image to disk 

- display current texture loaded into VRAM 
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